YAML formázó, ellenőrző és JSON ↔ YAML átalakító

A YAML ember által könnyen olvasható adatformátum, amelyet főleg konfigurációs fájlokhoz használnak: Docker Compose, Kubernetes, GitHub Actions és GitLab CI, Ansible, OpenAPI-leírások, statikus oldalgenerátorok és sok alkalmazás beállításai készülnek benne. A szerkezetet nem zárójelek, hanem a behúzás határozza meg, ezért egyetlen rossz helyen álló szóköz is megváltoztatja a jelentést, vagy hibát okoz.

A YAML eszköz három dolgot tud: ellenőrzi a YAML-t, és ha hibás, megmondja, melyik sorban és miért; JSON-ná alakítja, hogy lásd, a program pontosan hogyan értelmezi; és JSON-ból YAML-t készít, például ha egy API-válaszból konfigurációs fájlt szeretnél.

A gyakorlatban előforduló YAML-elemek nagy részét kezeli:

• kulcs–érték párok és tetszőleges mélységű beágyazás,
• listák (- elem), listák listái, objektumokat tartalmazó listák (- nev: ...),
• idézőjeles szöveg (dupla idézőjelben a \n típusú escape-ekkel, aposztrófban a dupla aposztróffal),
• többsoros blokkszöveg: | (a sortöréseket megtartja) és > (egy sorba fűzi), a - és + végződéssel,
• egysoros lista és objektum: [a, b, c] és {a: 1, b: 2},
• számok, logikai értékek (true, false), null (~ vagy null),
• megjegyzések (#).

Nem támogatott: horgonyok és hivatkozások (&, *, <<), címkék (!!str, !Ref és társaik), több dokumentum egy fájlban (--- elválasztóval). Ezekre az eszköz hibát jelez, nem hallgat el adatot.

• Tabulátor a behúzásban: a YAML-ben csak szóközzel szabad behúzni. Az eszköz a tabulátort két szóköznek veszi, de a valódi programok gyakran elutasítják.
• Következetlen behúzás: ha egy kulcs egy szóközzel beljebb vagy kijjebb áll, mint a testvérei, az eszköz „váratlan behúzás” hibát jelez.
• Hiányzó szóköz a kettőspont után: kulcs:érték helyett kulcs: érték kell.
• Kettőspont vagy # jel az értékben: a cim: Budapest #1 értéke csak „Budapest”, mert a szóköz utáni # megjegyzést kezd. Tedd idézőjelbe: cim: "Budapest #1".
• A „norvég probléma”: a régebbi YAML-értelmezők a no, yes, on, off értékeket logikai értéknek vették (így lett az NO országkódból false). Az eszköz a YAML 1.2 szerint csak a true és false szót tekinti logikainak, de JSON → YAML irányban ezeket idézőjelbe teszi, hogy más programokban se okozzanak gondot.
• Ismétlődő kulcs: ugyanaz a kulcs kétszer egy szinten; az eszköz ezt is jelzi.

A JSON és a YAML ugyanazt az adatszerkezetet írja le, csak másképp: a JSON zárójelekkel és idézőjelekkel, a YAML behúzással. Minden JSON átírható YAML-be, és a fenti korlátokon belül fordítva is.

YAML → JSON irányban a kimenet kétszóközös behúzású, szépen formázott JSON. Ez akkor hasznos, ha egy programnak JSON kell, vagy ha meg akarod nézni, a YAML-ed pontosan milyen adatot jelent: így kiderül, ha egy érték szám helyett szöveg, vagy egy lista rossz helyre került.

JSON → YAML irányban a szövegeket csak akkor teszi idézőjelbe, ha szükséges (például ha számnak, logikai értéknek látszanának, vagy különleges jelet tartalmaznak), a többsoros szövegeket pedig | blokkszövegként írja.

A két irány egymás ellenőrzésére is jó: ha egy YAML-t JSON-ná, majd vissza alakítasz, és ugyanazt az adatot kapod, a fájl szerkezete rendben van.

A harmadik mód beolvassa a YAML-t, és egységes formában írja vissza: kétszóközös behúzással, egységes listajelöléssel és idézőjelezéssel. Ha a beolvasás sikeres, a YAML érvényes; ha nem, a hibaüzenet megmondja a sor számát. Fontos: a megjegyzések az átalakítás során elvesznek, mert a beolvasott adatszerkezet nem tárolja őket. Ha a megjegyzéseket meg kell tartanod, az ellenőrzés után az eredeti fájlodat javítsd, ne a formázott változatot mentsd el.

Az eredmény gépelés közben frissül, és egy gombbal visszatehető a bemenetbe. Mivel a konfigurációs fájlokban gyakran jelszavak, kulcsok és belső címek vannak, fontos: