YAML in JSON (und zurück)

Warum „no“ zu false wird: das Norwegen-Problem

YAML gibt es in zwei Versionen, die beide verwendet werden. 1.1 stammt aus dem Jahr 2005 und ist die Version von PyYAML, also von Python und Ansible; 1.2 stammt aus dem Jahr 2009 und wird von den neueren Parsern verwendet, auch von dem auf dieser Seite. Der Text der Datei ist derselbe, aber manche ohne Anführungszeichen geschriebenen Wörter bedeuten für die beiden Versionen verschiedene Dinge.

Das Beispiel, das dem Problem seinen Namen gab, ist der Ländercode von Norwegen: In einer Länderliste ist NO für einen 1.1-Parser der Boolean false, und Norwegen verschwindet. Es ist nicht der einzige Fall. yes, on und off sind ebenfalls Booleans, und tatsächlich wird der Schlüssel on: der Workflows von GitHub Actions, mit PyYAML gelesen, zu true. 0755 ist eine Oktalzahl mit dem Wert 493. 22:22, ein Port-Mapping in einer docker-compose-Datei, ist eine Zahl zur Basis 60 mit dem Wert 1342. In YAML 1.2 ist das alles Text, außer 0755, das zur Zahl 755 wird.

Deshalb wandelt die Seite nicht einfach nur um: Für jeden ohne Anführungszeichen geschriebenen Wert fragt sie beide Parser, was sie sehen, und wenn sie sich uneinig sind, sagt sie es dir, mit der Zeile, dem Wert hier und dem der anderen Version. Mit dem Menü YAML lesen als wählst du, welchen Parser die Seite nachahmt. Die 1.1-Lesart ist die von PyYAML, Zeichen für Zeichen; die 1.1-Spezifikation führt auch y und n als Booleans auf, PyYAML aber nicht, und hier folgt die Seite PyYAML, weil es der 1.1-Parser ist, den man tatsächlich zur Hand hat. Das Heilmittel ist in jedem Fall dasselbe: Anführungszeichen.

Fehler in der richtigen Zeile

Das ist der Grund, warum fast alle einen Konverter öffnen: Das Programm sagt, die Datei sei falsch, verrät aber nicht, wo. Hier hat jeder Fehler einen Namen, die Zeile und einen Ausschnitt mit hervorgehobener Zeile, und der Button Zu Zeile springen markiert sie im Feld.

Die häufigsten Fälle haben eine eigene Erklärung. Ein Tab in der Einrückung, den YAML nicht akzeptiert und der genau wie Leerzeichen aussieht (im Ausschnitt erscheint er als Pfeil); und in der 1.1-Lesart auch einer nach dem Doppelpunkt oder am Zeilenende, den YAML 1.2 durchlässt und PyYAML nicht. Eine falsche Einrückung gegenüber den Zeilen derselben Ebene. Ein Wert mit einem Doppelpunkt und einem Leerzeichen danach, wie title: Rom: ein Reiseführer, den YAML für einen neuen Schlüssel hält. Ein Apostroph in einfachen Anführungszeichen, wie in 'Wie geht's?', der den Text auf halber Strecke schließt. Ein Wert ohne Anführungszeichen, der mit einem At-Zeichen beginnt, wie @types/node, oder mit einer Ansible-Variablen, wie {{ app_version }}. Das fehlende Leerzeichen nach dem Doppelpunkt. Ein doppelter Schlüssel, den PyYAML kommentarlos hinnehmen würde, wobei es den letzten behält.

Der fieseste Fall ist das offen gelassene Anführungszeichen: Der Parser bemerkt es erst Zeilen später und zeigt auf die falsche Zeile. Hier sucht die Seite die Zeile, in der das Anführungszeichen oder die Klammer geöffnet und nicht geschlossen wird, und hebt diese hervor. Die ursprüngliche Meldung des Parsers steht trotzdem darunter, für alle, die sie sehen wollen.

Was JSON nicht ausdrücken kann, sagt dir die Seite

Die Datumsangaben bleiben Text, genau wie geschrieben, weil JSON keinen Typ für Datumsangaben hat; die Seite listet die Zeilen auf, weil PyYAML stattdessen Datumswerte daraus machen würde. Die ganzen Zahlen über 2^53, etwa ein zwanzigstelliger Bestellcode, werden im JSON Ziffer für Ziffer geschrieben, aber die Seite warnt, dass ein JavaScript-Programm, das sie wieder einliest, sie rundet: Aus 12345678901234567890 würde 12345678901234567000. Die Werte Unendlich und „keine Zahl“ werden zu null und aufgelistet. Zahlen, die ihre Form ändern, werden gesondert markiert: 3.10 wird zu 3.1, das ist dieselbe Zahl, aber nicht dieselbe Python-Version.

Die Tags wie !Ref und !Sub von CloudFormation oder !reference von GitLab gibt es in JSON nicht: Der Wert bleibt, das Tag nicht, und die Seite listet auf, welche und wo. Mehrere durch --- getrennte Dokumente werden zu einer Liste. Die Anker und Aliasse werden aufgelöst, und dabei gilt eine ausdrücklich genannte Grenze: Fügt die Auflösung mehr als 100.000 Werte hinzu, stoppt die Umwandlung. Das ist die Abwehr gegen den Angriff namens „Billion Laughs“: zehn Zeilen, die aufgelöst zu einer Milliarde Werte werden und jedes Programm einfrieren, das sie bis zum Ende liest.

JSON in YAML: die Anführungszeichen, die wirklich nötig sind

In der anderen Richtung ist das Risiko umgekehrt. Ein Text wie "no", "010" oder "12:30" ist in JSON eindeutig ein Text; ohne Anführungszeichen in YAML geschrieben, macht der nächstbeste 1.1-Parser daraus einen Boolean oder eine Zahl. Hier kommt jeder Text, den auch nur einer der beiden Parser anders lesen würde, in Anführungszeichen, und die Seite sagt dir, welche.

Wähle die Einrückung, zwei oder vier Leerzeichen, oder die kompakte Form in einer einzigen Zeile. Ist das JSON eine Liste, kannst du es in mehrere YAML-Dokumente verwandeln, getrennt durch ---, so wie man es bei Kubernetes-Dateien macht. Und wenn sich das JSON nicht lesen lässt, hat der Fehler auch hier einen Namen: das überzählige Komma vor der Klammer, einfache Anführungszeichen, der Kommentar, der Schlüssel ohne Anführungszeichen. Der JSON-Parser wurde eigens geschrieben, statt den des Browsers zu verwenden, der große ganze Zahlen rundet und den Fehler in jedem Browser anders anzeigt. Um ein JSON aufzuräumen, einzurücken oder seine Schlüssel zu sortieren, ohne das Format zu wechseln, gibt es JSON formatieren und validieren.

So wurde getestet

Der Prüfer ist nicht diese Seite, sondern PyYAML, der YAML-Parser von Python, den wir auf zwei Arten einsetzen. So wie er ist, liefert er die 1.1-Lesart; mit den Regeln des Core Schema, neu geschrieben nach dem Text der 1.2-Spezifikation, liefert er die 1.2-Lesart. Bei 500 zufällig erzeugten Dokumenten, gespickt mit den oben genannten Fallen, mit Ankern, Merges und mehreren Dokumenten, müssen die Werte der Seite in beiden Lesarten mit seinen eigenen übereinstimmen, und die Liste der markierten Zeilen muss genau die Liste der Zeilen sein, in denen sich die beiden PyYAML-Lesarten unterscheiden, keine mehr und keine weniger. Dasselbe gilt für Tabs: Bei 600 Dokumenten mit einem zufällig eingefügten Tab akzeptiert und verwirft die 1.1-Lesart der Seite genau die, die PyYAML akzeptiert und verwirft, und wenn sie wegen des Tabs anhält, zeigt sie auf dieselbe Zeile und dieselbe Spalte.

In der anderen Richtung machen 400 zufällig erzeugte JSON-Strukturen, geschrieben mit drei verschiedenen Einrückungen, den kompletten Hin- und Rückweg: von JSON zu YAML und zurück zu JSON, und am Ende müssen sie identisch herauskommen. Unterwegs wird das erzeugte YAML von PyYAML in beiden Versionen zurückgelesen und muss dieselben Daten liefern wie das Ausgangs-JSON. Schließlich wird der JSON-Parser mit dem json-Modul von Python an 1.200 absichtlich verdorbenen Texten verglichen: Beide müssen dieselben akzeptieren und verwerfen und auf dieselbe Zeile zeigen.

Was das Tool nicht kann

Es behält keine Kommentare. JSON hat keine, also verschwinden sie von YAML zu JSON und tauchen auf dem Rückweg nicht wieder auf. Es prüft nicht, ob die Datei eine gültige Konfiguration für das Programm ist, das sie lesen wird: Nur Docker weiß, ob eine docker-compose-Datei die richtigen Felder hat. Es wandelt CloudFormation-Tags nicht in die lange Form um, die im JSON dieses Dienstes verwendet wird, sondern entfernt sie und sagt das. Es errät nicht jede Kodierung: Es liest UTF-8 und UTF-16, und eine in einer anderen Kodierung gespeicherte Datei wird als Windows-1252 gelesen, mit einem Hinweis darauf.

Es wandelt keine anderen Formate um. Für XML gibt es XML in JSON und zurück, um eine JSON-Liste in eine Tabelle zu verwandeln, gibt es JSON in CSV, und wenn die YAML-Datei in einer Antwort von ChatGPT oder Claude steckt, gibt es zum sauberen Herausholen Code aus KI-Antworten extrahieren.