YAML wirkt freundlich und beißt

Eine Obermenge von JSON, plus eine gefährliche Idee

YAML 1.2 stellt die Beziehung ausdrücklich fest: JSON ist eine Teilmenge von YAML, und ein konformer YAML-Prozessor akzeptiert jedes JSON-Dokument. Führ es aus, und die Behauptung hält — {"a": 1, "b": [1,2,3]} an js-yaml gegeben, kommt genau das erwartete Objekt zurück. Alles, was der vorige Artikel über JSONs fehlende Typen sagte, gilt hier also unverändert weiter. YAML gibt dir keinen von Float unterschiedenen Ganzzahltyp, keinen Binärtyp und kein Schema.

Was YAML hinzufügt, ist Bequemlichkeit für Menschen: Kommentare, keine Anführungszeichen an Schlüsseln, keine an den meisten Zeichenketten, keine geschweiften Klammern, keine Kommas, Blocktext, der seine Zeilenumbrüche behält, und ein Referenzmechanismus, mit dem ein Wert einmal geschrieben und wiederverwendet wird. Das sind echte Verbesserungen für eine Datei, die ein Mensch pflegt, und deshalb steuert YAML die Konfiguration des größten Teils der heute eingesetzten Deployment-Werkzeuge.

Die gefährliche Idee ist genau die, die all das möglich macht. Wenn Schlüssel und Zeichenketten keine Anführungszeichen brauchen, muss der Parser entscheiden, was ein ungequotetes Token bedeutet — YAML nennt diesen Schritt Auflösung: Ein einfacher Skalar wird gegen eine Menge regulärer Ausdrücke geprüft und bekommt einen Typ zugewiesen. Daher stammt jede Überraschung in diesem Artikel, und das ist zugleich der Teil der Sprache, der sich zwischen YAML 1.1 und YAML 1.2 geändert hat — dieselbe Datei kann also je nach lesender Bibliothek zwei verschiedene Dinge bedeuten.

Das Norwegen-Problem und welche Spezifikationsversion du wirklich hast

YAML 1.1 definierte einen Booleschen Typ mit großzügigem Tokenvorrat: true und false, aber auch yes und no, on und off, und im Typrepositorium die Einzelbuchstaben y und n. Eine Datei mit Ländercodes macht deshalb aus Norwegen einen Booleschen Wert, denn der ISO-Code Norwegens ist NO. Das ist der ganze berühmte Fehler — und kein Parserdefekt, sondern die Spezifikation, die tut, was dasteht.

YAML 1.2 hat das behoben, indem es das Kernschema verkleinerte. Das Boolesche Tag passt nur noch auf true und false, in wenigen Schreibweisen. Alles andere bleibt eine Zeichenkette. Deine Datei trägt aber keine Version, und fast niemand schreibt die %YAML-Direktive, die eine deklarieren würde — die geltende Version ist also die, die deine Bibliothek umsetzt, und beide sind heute noch breit im Produktivbetrieb.

Prüfe also, statt anzunehmen. Der YAML-Pfad dieser Seite nutzt js-yaml 4.3.0, dessen Paketbeschreibung es als YAML-1.2-Parser und -Serialisierer ausweist, und das Testdokument hindurchgeschickt liefert für den Norwegen-Fall die Zeichenkette "no" — unter allen vier seiner Schemata, von failsafe bis default. Dasselbe Dokument durch PyYAML 6.0.3, einen YAML-1.1-Parser, liefert Pythons False. Dieselben Bytes, entgegengesetzte Bedeutungen, und keine der beiden Bibliotheken irrt sich. Nimm dir drei Minuten und schick deine eigene Datei durch deinen eigenen Parser, bevor du irgendetwas glaubst, was online darüber steht — auch dies hier.

Zahlen, die nicht die sind, die du getippt hast

Die teuerste Falle überstand den Versionswechsel unangetastet. Schreib version: 1.10, und beide Parser liefern die Gleitkommazahl 1,1 — js-yaml gibt 1.1, PyYAML gibt 1.1 als Float. YAML hat sie als Zahl aufgelöst, und eine Zahl hat keine abschließende Null: Aus deiner Version 1.10 wurde Version 1.1, die vor 1.2 und 1.9 einsortiert. Quote sie, und sie überlebt: "1.10" kommt in beiden als Zeichenkette 1.10 zurück. Versions-, Teile- und Modellnummern und alles andere mit bedeutungstragender Endziffer müssen gequotet werden, in jeder Version der Spezifikation.

Führende Nullen sind schlimmer, weil die beiden Versionen sich über das Wie uneinig sind. Schreib zip: 01234, und js-yaml liefert die Zahl 1234 — die führende Null ist schlicht weg, denn das Ganzzahlmuster von YAML 1.2 ist ein gewöhnlicher Dezimalwert. PyYAML liefert 668, denn unter YAML 1.1 bedeutet eine führende Null oktal, und 1234 zur Basis 8 gelesen ergibt 668. Eine Postleitzahl, eine Bankleitzahl oder eine Kontonummer ohne Anführungszeichen wird also von beiden Parsern beschädigt, zu zwei verschiedenen falschen Werten. Umgekehrt löst die eigene Oktalnotation von YAML 1.2, 0o17, in js-yaml zu 15 auf und bleibt in PyYAML die Zeichenkette "0o17", das die neuere Form nicht kennt.

Die letzte Zahlenfalle ist die sexagesimale, und sie starb mit YAML 1.1. Jene Version löste durch Doppelpunkte getrennte Zifferngruppen als Ganzzahlen zur Basis 60 auf: 12:30:00 wurde 45000 und 22:22 wurde 1342. Führ es aus: PyYAML liefert genau diese beiden Ganzzahlen, js-yaml die Zeichenketten. Ein crontab-artiger Zeitplan, eine Dauer, ein MAC-Adressfragment oder ein Musikzeitstempel, ungequotet in einer 1.1-Datei geschrieben, wird zu einer Ganzzahl ohne erkennbaren Bezug zum Geschriebenen — 45000 ist die Sekundenzahl von zwölfeinhalb Stunden, immerhin logisch, und 1342 ist 22 mal 60 plus 22, was niemand gemeint hat.

Leerraum, verbotene Tabulatoren und die zwei Block-Skalare

Einrückung ist in YAML Struktur, Leerraum also nicht kosmetisch, und ein Formatierer darf ihn nicht frei umbrechen. Die Spezifikation verbietet Tabulatoren in der Einrückung vollständig — nicht rät ab, verbietet —, weil ein Tabulator keine definierte Breite hat und der Parser nicht wissen könnte, wie tief du sein wolltest. Gib js-yaml eine tabulatoreingerückte Liste, und es hält mit einer präzisen Beschwerde an: tab characters must not be used in indentation, Zeile 2 Spalte 1. Dieser Fehler ist der häufigste YAML-Fehlschlag in einem Editor, der führende Leerzeichen hilfsbereit umwandelt.

Mehrzeiliger Text nutzt einen von zwei Blockstilen, und der Unterschied ist genau das, was mit deinen Zeilenumbrüchen geschieht. Der literale Stil, mit einem senkrechten Strich geschrieben, behält jeden Umbruch: Ein zweizeiliger Block kommt als "line one\nline two\n" zurück. Der gefaltete Stil, mit einem Größer-als-Zeichen geschrieben, verbindet aufeinanderfolgende Zeilen mit einem Leerzeichen: Derselbe Block kommt als "line one line two\n" zurück. Der gefaltete Stil behält eine Leerzeile aber als echten Umbruch, sodass ein zweiabsätziger gefalteter Block "para one line a para one line b\npara two\n" liefert — ein verbundener Absatz, dann ein echter Bruch.

Über dem Stil steht ein Abschneide-Indikator, der über den abschließenden Zeilenumbruch entscheidet — der Teil, den man vergisst. Die Vorgabe, ohne Zusatz geschrieben, ist clip: Genau ein abschließender Umbruch bleibt. Ein Minuszeichen entfernt ihn, sodass derselbe Block als "line one\nline two" ganz ohne abschließenden Umbruch zurückkommt. Ein Pluszeichen behält alle abschließenden Leerzeilen: Ein Block mit folgender Leerzeile liefert "line one\nline two\n\n". Das zählt mehr, als es klingt: Ein Zertifikat, ein SSH-Schlüssel oder ein in eine Konfigurationsdatei eingebettetes Shell-Skript braucht seinen abschließenden Umbruch meist, ein eingebettetes Token oder Passwort darf ihn meist nicht haben. Ein Fehler dabei erzeugt eine Abweichung an einem Wert, der in jedem Diff identisch aussieht.

Anker und Aliase: ein echtes Feature, das auch eine Bombe ist

Ein Anker benennt einen Knoten mit einem Und-Zeichen, ein Alias verweist mit einem Sternchen darauf zurück, und der Merge-Schlüssel zieht die Schlüssel einer Zuordnung in eine andere. Zusammen beseitigen sie die größte Driftquelle in Konfigurationen: Schreib deine Vorgaben einmal und überschreib dann die zwei Werte, die sich pro Umgebung unterscheiden. Führ es aus, und es tut genau das Gewünschte — ein Basisblock mit Zeitlimit 30 und drei Wiederholungen, in dev hineingemischt und mit Zeitlimit 5 überschrieben, gibt dev ein Zeitlimit von 5 und drei Wiederholungen, während prod 30 und 3 behält.

Eine Feinheit sollte man kennen, bevor man sich darauf verlässt: Ein Alias kopiert nicht, er teilt. Lade ein Dokument, in dem zwei Listeneinträge denselben Anker aliasieren, und die beiden Einträge sind dasselbe Objekt — strikte Gleichheit zwischen ihnen ist wahr, ebenso mit dem Original. Verändere eines nach dem Laden, und du hast alle verändert. Für schreibgeschützte Konfiguration ist das harmlos und in Code, der den geladenen Baum an Ort und Stelle normalisiert oder patcht, eine echte Falle.

Genau dieses Teilen macht den Expansionsangriff möglich. Verkette Anker so, dass jede Ebene eine Liste von neun Verweisen auf die darunterliegende ist: Die Größe des logischen Dokuments ist neun hoch Tiefe, während die Datei winzig bleibt. Mit js-yaml gemessen: Vier Ebenen sind 241 Byte YAML und 54 127 Byte JSON, Faktor 225; sechs Ebenen sind 349 Byte und 4,38 MB, Faktor 12 563; sieben Ebenen sind 403 Byte und 39,46 MB, Faktor 97 914. Bei neun Ebenen liegt die logische Knotenzahl bei 387 420 489. Beachte, wo die Kosten wirklich anfallen: js-yaml parste all das in unter zwei Millisekunden, denn die Aliase sind geteilte Referenzen und der Graph im Speicher bleibt klein. Das Serialisieren des Ergebnisses dauerte bei sieben Ebenen 363 Millisekunden. Die Verteidigung ist also nicht nur ein Parserlimit — sie besteht darin, einen Baum aus nicht vertrauenswürdigem YAML nicht tief zu durchlaufen, nicht tief zu kopieren und nicht zu serialisieren, dazu eine Größenobergrenze für die Eingabe und ein Alias-Expansionslimit, falls deine Bibliothek eines anbietet.

Die Regel, und was ein Formatierer für dich tun kann und was nicht

Quote jede Zeichenkette, die sich als etwas anderes lesen ließe. In der Praxis ist das eine kurze, merkbare Liste: alles, was yes, no, on, off, y, n, true oder false ist oder enthält; jeder Ländercode, besonders NO; jeder Wert mit führender Null; jede Versions- oder Teilenummer mit abschließender Null nach dem Dezimalzeichen; alles mit Doppelpunkten darin, etwa eine Uhrzeit oder eine Dauer; die Wörter null und none sowie die Tilde; und alles, was wie eine Zahl aussieht, aber in Wahrheit eine Kennung ist. Einfache Anführungszeichen sind die sicherste Form, denn in ihnen ist nichts eine Escape-Sequenz: Ein Windows-Pfad oder ein regulärer Ausdruck kommt unversehrt durch.

Eines sollte klar sein, denn es ist ein verbreitetes Missverständnis. Der YAML-Formatierer dieser Seite parst kein YAML. Er normalisiert den Text — wandelt Tabulatoren in zwei Leerzeichen, entfernt abschließenden Leerraum, staucht Folgen von Leerzeilen zusammen und lässt beim Minifizieren Kommentare und Leerzeilen weg — und prüft separat auf den einen harten Fehler, einen Tabulator in der Einrückung. Er löst nie einen Skalar auf, kann dein NO also nicht in false und dein 1.10 nicht in 1,1 verwandeln, und er formatiert deine Block-Skalare nicht um. Das ist Absicht: Ein Formatierer, der deine Datei durch einen Parser hin und zurück schickte, würde stillschweigend dessen Fassung der Auflösungsregeln anwenden und dir ein anderes Dokument zurückgeben.

Aus demselben Grund: Behandle jede YAML-zu-JSON-Umwandlung als verlustbehafteten Schritt und sieh dir das Ergebnis an. Die Umwandlung ist genau der Moment, in dem die Auflösungsregeln greifen — also auch der billigste Weg herauszufinden, was dein Parser wirklich in deiner Datei liest: Gib ihm deine Konfiguration, lies das JSON, und jeder Quoting-Fehler aus diesem Artikel wird in einem Durchgang sichtbar.

Häufige Fragen

Ist das Norwegen-Problem behoben, und woran erkenne ich, welche Version mein Parser umsetzt?

In der Spezifikation ist es behoben, in deinem Programm nicht zwangsläufig. YAML 1.2 hat yes, no, on und off aus dem Booleschen Tag des Kernschemas entfernt, ein 1.2-Parser lässt sie also als Zeichenketten stehen. YAML 1.1 löste sie alle auf, dazu die Einzelbuchstaben y und n aus seinem Typrepositorium — daher wurde der ISO-Ländercode NO zu false. Deine Datei deklariert keine Version — die %YAML-Direktive gibt es, aber praktisch niemand schreibt sie —, das Verhalten kommt also vollständig von der Bibliothek. Der verlässliche Test dauert eine Minute: Lade ein zweizeiliges Dokument mit einem Schlüssel, dessen einfacher Wert no ist, und gib den Typ des Ergebnisses aus. Hier gemessen liefert js-yaml 4.3.0 die Zeichenkette "no", und zwar unter allen vier mitgelieferten Schemata, von failsafe bis zur Vorgabe. PyYAML 6.0.3 liefert Pythons False. Beide sind korrekte Umsetzungen unterschiedlicher Spezifikationsversionen. Beachte außerdem, dass sich Implementierungen selbst innerhalb von 1.1 bei den Einzelbuchstabenformen unterscheiden — PyYAML lässt ein nacktes y und ein nacktes n als Zeichenketten —, Testen schlägt also Lesen. Und wie die Antwort auch ausfällt: Den Wert zu quoten kostet nichts und wirkt in jeder Version.

Warum wurde aus meiner Versionsnummer 1.10 die Zahl 1,1?

Weil sie zum Float-Muster passte, und ein Float hat kein Gedächtnis für abschließende Nullen. Beide Parser stimmen hier überein — js-yaml liefert 1.1 und PyYAML liefert 1.1 als Float —, das ist also keine Frage der Spezifikationsversion, und Quoten ist die einzige Abhilfe. Der Schaden geht über einen Anzeigefehler hinaus. Die Sortierung bricht, denn als Zahl liegt 1,1 zwischen 1,09 und 1,2, während als Versionszeichenkette 1.10 nach 1.9 gehört. Die Gleichheit bricht, denn eine Suche nach der Version namens 1.10 findet den Schlüssel nicht mehr. Und ein erneutes Serialisieren schreibt 1.1 auf die Platte zurück: Der Fehler wird in deinem Repository dauerhaft, und das Diff zeigt eine plausibel aussehende Ein-Zeichen-Änderung. Dieselbe Falle erwischt jede gepunktete Kennung mit zwei Bestandteilen: eine Kapitelnummer, einen Firmware-Stand, eine Schemaversion, einen dezimalen Produktcode. Schreib sie als "1.10" in Anführungszeichen. Brauchst du echte Ordnungssemantik, nimm eine dreiteilige semantische Version: Sie enthält zwei Punkte und kann daher gar nicht auf das Float-Muster passen — 1.10.0 ist in jedem Parser auch ohne Anführungszeichen eine Zeichenkette, wobei das Quoten trotzdem nichts kostet und dir das Nachdenken erspart.

Wann nehme ich den senkrechten Strich und wann das Größer-als-Zeichen?

Nimm den senkrechten Strich, den literalen Stil, immer dann, wenn die Zeilenumbrüche Teil des Werts sind: ein Shell-Skript, ein Zertifikat, ein SSH-Schlüssel, eine SQL-Anweisung, eine eingebettete Konfigurationsdatei, ein ASCII-Diagramm. Gemessen liefert ein zweizeiliger literaler Block "line one\nline two\n" — jeder Umbruch erhalten, plus einer am Ende. Nimm das Größer-als-Zeichen, den gefalteten Stil, für Fließtext, den du in der Quelldatei umbrechen, aber einzeilig speichern willst: eine lange Beschreibung, eine Hilfemeldung, eine Commit-Vorlage. Derselbe Block gefaltet liefert "line one line two\n" — der innere Umbruch wurde ein Leerzeichen. Der gefaltete Stil achtet Leerzeilen weiterhin als Absatzgrenzen: Ein gefalteter Block mit einer Leerzeile in der Mitte liefert "para one line a para one line b\npara two\n". Wähle dann den Abschneide-Indikator bewusst. Die nackte Form behält genau einen abschließenden Umbruch, ein Minuszeichen entfernt ihn ganz, ein Pluszeichen behält alle. Ein PEM-Zertifikat braucht seinen abschließenden Umbruch, die nackte Form ist also richtig. Ein Token oder ein einzeiliges Geheimnis darf keinen haben, dafür nimm das Minus. Genau dieses Detail erzeugt die rätselhafte Signaturabweichung oder den openssl-Parsefehler an einem Wert, der in der Datei korrekt aussieht.

Sind Anker und Aliase in Produktionskonfigurationen sicher?

In Dateien, die du schreibst und prüfst, ja — sie sind das richtige Werkzeug für gemeinsame Vorgaben, und der Merge-Schlüssel erzeugt genau das Umgebungs-Override-Muster, das die meisten Deployments brauchen. Zwei Vorbehalte gelten selbst dort. Ein Alias teilt den Knoten, statt ihn zu kopieren — hier durch strikte Gleichheit zweier aliasierter Einträge bestätigt —, jeder Code, der den geladenen Baum an Ort und Stelle verändert, ändert also alle Vorkommen auf einmal. Und der Merge-Schlüssel ist ein YAML-1.1-Feature, das per Konvention weitergetragen wird, kein Teil des 1.2-Kernschemas; die Unterstützung schwankt daher je nach Bibliothek — prüfe deine, bevor du dich darauf verlässt. Bei Dateien von außerhalb deiner Organisation behandle Aliase als Vektor zur Ressourcenerschöpfung. Ein neunfacher Fächer über sieben Ebenen ergab hier 403 Byte Eingabe und 39,46 MB Ausgabe, Faktor 97 914, und neun Ebenen kämen auf 387 420 489 logische Knoten. Wo die Kosten anfallen, sollte man genau wissen: js-yaml parste jeden dieser Fälle in unter zwei Millisekunden, weil Aliase geteilte Referenzen bleiben; die Rechnung über 363 Millisekunden kam beim Serialisieren des Ergebnisses. Die Verteidigung ist also eine Größenobergrenze für die Eingabe, ein Alias-Expansionslimit, falls deine Bibliothek eines bietet, und eine Regel gegen Tiefkopieren oder Serialisieren eines aus nicht vertrauenswürdigem YAML geladenen Baums.

Ändert der YAML-Formatierer dieser Seite die Bedeutung meiner Werte?

Nein, denn er parst sie nie. Er arbeitet auf Textebene: Er ersetzt Tabulatoren durch zwei Leerzeichen, entfernt abschließenden Leerraum aus jeder Zeile, staucht Folgen von drei oder mehr Leerzeilen auf eine zusammen und lässt im Minify-Modus Kommentarzeilen und Leerzeilen weg. Er führt außerdem eine Prüfung durch — den einen harten Fehler, den die Spezifikation für Leerraum definiert — und meldet die Zeilennummer jedes in der Einrückung gefundenen Tabulators. Weil nie ein Skalar aufgelöst wird, bleibt ein nacktes NO die zwei Zeichen NO, 1.10 behält seine abschließende Null, und deine Block-Skalare kommen exakt so zurück, wie du sie geschrieben hast. Das ist eine bewusste Entwurfsentscheidung: Ein auf einem Parser gebauter Formatierer würde deine Datei durch dessen Auflösungsregeln schicken und ein Dokument mit anderen Werten zurückgeben — genau der Fehlschlag, um den es in diesem Artikel geht. Willst du sehen, wie deine Datei sich auflöst, wandle sie stattdessen in JSON um: Das ist der Schritt, in dem die Auflösung passiert, und das JSON zu lesen ist die schnellste Prüfung deines Quotings.