Wat is een YAML-bestand?

YAML is een puur tekstformaat dat in elke editor opengaat. Het wordt gebruikt voor gegevens tussen programma’s verplaatsen en bewerken.

De extensie is .yaml en de volledige naam YAML Ain't Markup Language. Allebei zeggen ze minder dan wat het bestand kan bevatten, en daar gaat de rest van deze pagina over.

Het gaat terug tot 2001. De specificatie is YAML 1.2.

De leeftijd is om een praktische reden interessant: hoe ouder een formaat, hoe meer programma’s de tijd hebben gehad om het te leren.

Ze is volledig gepubliceerd, dus wie het formaat wil uitvoeren kan dat uit het document doen in plaats van door te kijken hoe anderen het doen. Daarom duikt het in zo veel programma’s op, en daarom gaan bestanden van twintig jaar geleden nog steeds open. Openbaar is niet hetzelfde als royaltyvrij: waar een formaat een codec omhult, is de octrooilicentie een aparte vraag waarop de standaard geen antwoord geeft.

YAML bewaart zijn inhoud precies. Opnieuw opslaan verandert niets, dus je kunt het zo vaak openen, bewerken en wegschrijven als je wilt zonder dat er schade opstapelt — en dat is wat er een werkformaat van maakt in plaats van een afleverformaat.

YAML heeft een commentaarsyntaxis — dat is het verschil tussen een bestand dat een mens onderhoudt en een bestand dat een programma schrijft. Bij het converteren naar een formaat zonder commentaar zijn ze het eerste wat verdwijnt, en er wordt niet gewaarschuwd.

Visual Studio Code en yq lezen het, en de meeste programma’s van dezelfde soort ook.

Als een bestand niet opengaat ligt het zelden aan het formaat — vaker is het programma ouder dan het formaat. Converteren naar iets ouders is de betrouwbare weg eromheen, en daarvoor is de rest van deze site bedoeld.

Geen enkele browser leest het.

Dat is veruit de meest voorkomende reden om het te converteren: niet dat het formaat slecht is, maar dat de plek waar je het bestand wilt tonen het niet kan lezen.

YAML is bedoeld om te openen en te wijzigen. Houd het bestand in dit formaat zolang het werk loopt, en exporteer eruit wanneer er een afgeronde versie nodig is.

Heel weinig mensen kiezen YAML. Ze krijgen het overhandigd: Kubernetes-manifesten, GitHub Actions- en GitLab CI-pijplijnen, Ansible-playbooks, Docker Compose, OpenAPI-specificaties. Al die ecosystemen kozen ervoor, en ze zijn groot genoeg dat het formaat geen beslissing is die iemand nog herziet.

Dat bepaalt wat een nuttige pagina erover is. De vraag is zelden of je YAML moet gebruiken — het is hoe je de specifieke manieren vermijdt waarop het misgaat, want het faalt stiller dan elk ander gangbaar configuratieformaat.

Er zijn geen haakjes en geen sluitmarkeringen. Hoe diep een regel inspringt, bepaalt waar hij bij hoort, dus één spatie op de verkeerde plek verandert de betekenis van het document — en levert vaak nog een geldig document op, alleen een ander.

Twee regels voorkomen het meeste. Gebruik nooit tabs: de specificatie verbiedt ze. En houd de inspringing consistent, twee spaties per niveau volgens conventie, want breedtes mengen binnen een bestand is legaal en maakt de structuur onleesbaar op het oog.

YAML gokt wat een kale waarde is, en de gokken hebben echte storingen veroorzaakt. De beroemdste is het Noorwegenprobleem: in YAML 1.1 is een niet-geciteerde no de boolean false, dus een lijst landcodes maakt van NO false. Hetzelfde geldt voor on, off, y en n.

Versienummers zijn de tweede: 1.20 wordt het kommagetal 1.2, en de laatste nul verdwijnt. Tijden zijn de derde: 22:30 kan als een zestigtallig getal gelezen worden in plaats van als tekst.

De verdediging is een gewoonte, niet kennis: zet aanhalingstekens om alles dat tekst moet zijn. YAML 1.2 loste verschillende hiervan op en veel parsers implementeren nog 1.1, dus de gewoonte beschermt je, niet de specificatie.

YAML kan een blok eenmalig definiëren en hergebruiken. Een anker markeert het, een alias verwijst ernaar, en een merge key vouwt een gedeeld blok op meerdere plekken in — hoe een CI-pijplijn dezelfde zes regels niet in elke job hoeft te herhalen.

Het is echt nuttig en het is waar YAML ophoudt leesbaar te zijn voor wie de syntax niet kent. Twee waarschuwingen: een alias is een verwijzing, geen kopie; en verschillende tools implementeren ankers helemaal niet.

Een blokscalair geschreven met een verticale streep behoudt de regeleindes: goed voor een script of certificaat. Geschreven met een groter-dan-teken vouwt het de regels tot één, goed voor een lange zin die voor leesbaarheid is afgebroken.

Elk neemt een achtervoegsel dat de laatste regeleinde regelt — een min strript hem, een plus behoudt elke afsluitende. Dat telt zwaarder dan het klinkt wanneer de waarde een sleutel of token is: een onverwachte afsluitende regeleinde is de klassieke reden dat een certificaat geweigerd wordt.

Drie streepjes op een eigen regel starten een nieuw document, dus één bestand kan een reeks bevatten. Kubernetes gebruikt dit voortdurend — een deployment, een service en een configmap in één bestand.

De moeite waard om te weten, want het verandert wat "dit bestand parsen" betekent. Een parser die één document leest, negeert stilletjes alles na de eerste scheiding, hoe halve configuratie zonder foutmelding verdwijnt.

Elk JSON-document is geldige YAML, want YAML 1.2 is als superset gedefinieerd. JSON omzetten naar YAML is dus triviaal en vooral cosmetisch.

De andere richting verliest wat JSON geen plek voor heeft: commentaar, ankers, en het onderscheid tussen de manieren om een meerregelige tekenreeks te schrijven. Een Kubernetes-manifest via JSON heen-en-weer sturen strippt dus elk verklarend commentaar erin.

Gebruik een editor met YAML-modus. Hij toont inspringgidsen, zet tabs om, en markeert een structurele fout ter plekke in plaats van een pijplijn het te laten ontdekken.

En valideer voor het verzenden wanneer een schema bestaat. Kubernetes, OpenAPI en de meeste CI-systemen publiceren er een, en een validerende controle vangt de misplaatste sleutel die een parser blij accepteert en het systeem om drie uur ’s nachts afwijst.