Was ist eine YAML-Datei?

YAML ist ein reines Textformat, das sich in jedem Editor öffnen lässt. Eingesetzt wird es für den Austausch zwischen Programmen und die Bearbeitung.

Die Endung lautet .yaml, der volle Name YAML Ain't Markup Language. Beides sagt weniger aus als das, was die Datei halten kann — und davon handelt der Rest dieser Seite.

Es geht auf 2001 zurück. Die Spezifikation ist YAML 1.2.

Das Alter ist aus einem praktischen Grund interessant: je älter ein Format, desto mehr Programme hatten Zeit, es zu lernen.

Sie ist vollständig veröffentlicht, das Format lässt sich also aus dem Dokument umsetzen statt durch Nachsehen. Deshalb taucht es in so vielen Programmen auf, und deshalb gehen Dateien von vor zwanzig Jahren heute noch auf. Veröffentlicht heißt allerdings nicht lizenzfrei: Wo ein Format einen Codec einpackt, ist die Patentfrage eine eigene, die der Standard nicht mitbeantwortet.

YAML speichert seinen Inhalt exakt. Erneutes Speichern ändert nichts, es lässt sich also beliebig oft öffnen, bearbeiten und wieder ablegen, ohne dass sich Schaden ansammelt — genau das macht es zu einem Arbeitsformat und nicht zu einem Ausgabeformat.

YAML hat eine Kommentarsyntax — das ist der Unterschied zwischen einer Datei, die ein Mensch pflegt, und einer, die ein Programm schreibt. Beim Umwandeln in ein Format ohne Kommentare sind sie das Erste, was verschwindet, und gewarnt wird nicht.

Visual Studio Code und yq lesen es, und die meisten Programme derselben Art ebenfalls.

Wenn eine Datei nicht aufgeht, liegt es selten am Format — häufiger daran, dass das Programm älter ist als das Format. Die Umwandlung in etwas Älteres ist der verlässliche Weg daran vorbei, und dafür gibt es den Rest dieser Website.

Kein Browser liest es.

Das ist der häufigste Grund, es umzuwandeln: nicht dass das Format schlecht wäre, sondern dass die Stelle, an der die Datei erscheinen soll, es nicht lesen kann.

YAML ist zum Öffnen und Ändern gedacht. Behalte die Datei in diesem Format, solange die Arbeit läuft, und exportiere daraus, wann immer eine fertige Fassung gebraucht wird.

Kaum jemand entscheidet sich für YAML. Es wird einem gereicht: Kubernetes-Manifeste, GitHub-Actions- und GitLab-CI-Pipelines, Ansible-Playbooks, Docker Compose, OpenAPI-Spezifikationen, Front Matter in statischen Websites. All diese Ökosysteme haben sich darauf festgelegt, und sie sind groß genug, dass die Formatwahl niemand mehr in Frage stellt.

Das bestimmt, wie eine nützliche Seite darüber aussehen muss. Die Frage ist selten, ob man YAML einsetzen sollte — sie ist, wie man die konkreten Arten vermeidet, auf die es scheitert, denn es scheitert leiser als jedes andere gebräuchliche Konfigurationsformat.

Es gibt keine Klammern und keine Abschlusszeichen. Wie tief eine Zeile eingerückt ist, entscheidet, wozu sie gehört — ein einziges Leerzeichen an der falschen Stelle ändert die Bedeutung des ganzen Dokuments, und häufig entsteht dabei ein Dokument, das immer noch gültig ist, nur eben ein anderes als das gemeinte.

Zwei Regeln verhindern die meisten Probleme. Nie Tabulatoren verwenden: Die Spezifikation verbietet sie, und ein Editor, der einen einfügt, erzeugt einen Parserfehler, dessen Meldung das selten deutlich sagt. Und die Einrückung konsequent gleich halten, üblicherweise zwei Leerzeichen pro Ebene, denn unterschiedliche Breiten innerhalb einer Datei sind zwar erlaubt, machen die Struktur aber auf den ersten Blick unlesbar.

YAML rät, wofür ein unmarkierter Wert steht, und diese Vermutungen haben schon echte Ausfälle verursacht. Am bekanntesten ist das Norwegen-Problem: In YAML 1.1 ist ein unquotiertes no der Wahrheitswert false, sodass eine Liste von Ländercodes aus NO ein false macht. Dasselbe passiert mit on, off, y und n.

Versionsnummern sind die zweite Falle: 1.20 wird als Fließkommazahl 1.2 gelesen, die abschließende Null verschwindet. Zeiten sind die dritte: 22:30 kann als Sexagesimalzahl statt als Text interpretiert werden. Und ein Wert wie 0755 wird mitunter als Oktalzahl gelesen.

Der Schutz ist eine Gewohnheit, kein Fachwissen: alles in Anführungszeichen setzen, was Text sein soll. Versionsnummern, Ländercodes, Kennungen, Uhrzeiten, alles mit führenden Nullen. YAML 1.2 hat einige dieser Fälle korrigiert, doch etliche Parser setzen noch immer 1.1 um — also schützt die Gewohnheit, nicht die Spezifikation.

YAML kann einen Block einmal definieren und mehrfach wiederverwenden. Ein Anker markiert ihn, ein Alias verweist darauf, und ein Merge-Schlüssel faltet einen gemeinsamen Block an mehreren Stellen ein — so vermeidet eine CI-Pipeline, dieselben sechs Zeilen in jedem Job zu wiederholen.

Das ist wirklich nützlich, und genau hier hört YAML auf, für jemanden lesbar zu sein, der die Syntax noch nicht kennt. Zwei praktische Warnungen: Ein Alias ist ein Verweis und keine Kopie, also ist das Geteilte tatsächlich geteilt; und etliche Werkzeuge, die YAML einlesen, unterstützen Anker gar nicht oder lösen sie auf überraschende Weise auf. Vor dem Aufbau einer großen Konfiguration darauf prüfen.

Ein mit senkrechtem Strich geschriebener Blockskalar behält die Zeilenumbrüche: richtig für ein Skript, ein Zertifikat, eine Nachricht mit Absätzen. Mit einem Größer-als-Zeichen geschrieben, werden die Zeilen zu einer zusammengefaltet — richtig für einen langen, im Text nur der Lesbarkeit wegen umgebrochenen Satz.

Beide nehmen ein Suffix, das den abschließenden Zeilenumbruch steuert — ein Minus entfernt ihn, ein Plus behält jeden. Das ist wichtiger, als es klingt, wenn der Wert ein Schlüssel, ein Token oder ein Skript ist: Ein unerwarteter abschließender Zeilenumbruch ist der klassische Grund, warum ein Zertifikat abgelehnt wird oder ein Befehl sich in einer Pipeline anders verhält als auf dem eigenen Rechner.

Drei Bindestriche allein auf einer Zeile beginnen ein neues Dokument, sodass eine einzige Datei eine ganze Folge davon enthalten kann. Kubernetes macht davon ständig Gebrauch — ein Deployment, ein Service und eine ConfigMap in einer Datei —, und jedes Werkzeug, das sie liest, erwartet genau das.

Es lohnt sich, das zu wissen, weil es ändert, was „diese Datei einlesen" bedeutet. Ein Parser, der nur ein Dokument liest, ignoriert still alles nach dem ersten Trenner, und so verschwindet die Hälfte einer Konfiguration ohne jede Fehlermeldung. Die passende Funktion heißt meist so, dass sie alle Dokumente lädt, nicht nur eines.

Jedes JSON-Dokument ist gültiges YAML, seit YAML 1.2 als Obermenge definiert wurde. Eine Umwandlung von JSON nach YAML ist deshalb trivial und fast rein kosmetisch — dieselben Daten, besser lesbar und jetzt fähig, Kommentare zu tragen.

Die andere Richtung verliert, wofür JSON schlicht keinen Platz hat: Kommentare, Anker und den Unterschied zwischen den verschiedenen Arten, mehrzeiligen Text zu schreiben. Ein Kubernetes-Manifest über JSON hin- und herzuwandeln streicht deshalb jeden erklärenden Kommentar darin — ein Verlust, den niemand bemerkt, bis er sechs Monate später wieder in der Datei landet.