YAML in JSON umwandeln

Ein bekannter Fall aus der CI/CD-Welt: Eine GitHub-Actions-Datei beginnt mit dem Schlüssel on:, gefolgt vom Ereignisnamen. In einer YAML-1.1-Lesart ist das Wort on aber kein Text, sondern ein Wahrheitswert — dieselbe Regel, die einen ISO-Ländercode NO in false verwandelt. Jahrelang lasen manche Werkzeuge in dieser Zeile also true statt eines Schlüssels namens on, ohne dass die Datei falsch aussah.

Genau solche Überraschungen macht diese Umwandlung sichtbar. JSON hat keine Abkürzungen, hinter denen sich ein Wert verstecken kann, also zeigt die Ausgabe genau das, was der Parser tatsächlich gelesen hat, statt das, was jemand getippt hat.

YAML-Dateien können mehrere Dokumente in einem Strom enthalten, getrennt durch --- Zeilen — eine Compose-Datei mit mehreren Diensten oder ein Manifest-Bündel nutzt das oft. JSON kennt das nicht: Eine JSON-Datei ist genau ein Wert, also verweigert der Parser die Umwandlung, statt still ein Dokument auszuwählen, und meldet die Zeile, an der das zweite Dokument beginnt.

Der Ausweg ist mechanisch: die Datei an den --- Markierungen teilen und jedes Dokument einzeln umwandeln, oder die Teile vorher selbst in eine Liste packen. Ein einzelnes führendes --- am Dateianfang stört nicht, nur ein zweites Dokument tut es.

Ein Anker und seine Aliase werden zu Kopien. Eine Konfigurationsdatei, die &defaults einmal definiert und aus sechs Blöcken referenziert, ergibt als JSON sechs vollständige Kopien, weil JSON keine Möglichkeit hat, auf einen an anderer Stelle definierten Wert zu verweisen.

Der Merge-Schlüssel ist die Stelle, an der es überrascht. Eine Zeile mit << und einem Alias dahinter ist eine YAML-1.1-Konvention zum Zusammenführen einer Zuordnung, gehört aber nicht zum YAML-1.2-Kernschema, und kommt deshalb als gewöhnlicher Schlüssel mit dem wörtlichen Namen "<<" heraus, dessen Wert die referenzierte Zuordnung ist. Die eigentlich erwarteten Schlüssel stehen dann eine Ebene tiefer, unter diesem Schlüssel.

CloudFormation-Kurzformen und ähnliche Dialekte hängen Bedeutung an eigene Tags: !Ref meinBucket, !GetAtt [ressource, attribut]. Der Parser kennt diese Tags nicht, löst jeden davon zu seinem nackten Wert auf und macht weiter — aus !Ref meinBucket wird die reine Zeichenkette "meinBucket".

Das ist die gefährlichste Stelle dieser Umwandlung, weil die JSON-Ausgabe gültig, plausibel und trotzdem falsch ist. Es bleibt kein Hinweis darauf, dass dort ein Tag stand. Wer eine YAML-Datei mit eigenen Tags konvertiert, bekommt ein Dokument, das nicht mehr das Gemeinte beschreibt — die einzige Absicherung ist, vorher zu wissen, dass die Datei solche Tags verwendet.

Der hier verwendete Parser setzt YAML 1.2 um, dessen Kernschema nur true und false als Wahrheitswerte kennt — yes, no, on, off, y und n bleiben Zeichenketten. Das ist der Grund, warum der eingangs erwähnte GitHub-Actions-Fall mit einem 1.2-Parser gar nicht erst passiert wäre.

Es ist ein Standardverhalten, keine Garantie: Eine Datei, die mit %YAML 1.1 beginnt, wird als 1.1 gelesen, und dann wird on tatsächlich zu true. Es sagt außerdem nur etwas über diesen Konverter — das Werkzeug, das eine YAML-Datei in Produktion liest, kann ebenso gut eine 1.1-Implementierung sein. Das JSON hier zeigt, was ein 1.2-Parser sieht, und genau deshalb ist es nützlich, wenn das Laufzeitsystem etwas anderes sieht.

Ein Wert wie 1.0 wird zur Zahl 1, also verliert eine gepinnte Versionsnummer ihre Nachkommastelle. Ein Wert wie 0755 wird zu 755. Anführungszeichen um den Wert in der Quelle halten ihn als Zeichenkette, was sich in der JSON-Ausgabe an den Anführungszeichen erkennen lässt — eine schnelle Methode, eine Datei auf Werte zu prüfen, die eigentlich quotiert gehören.

Große Ganzzahlen verlieren still an Genauigkeit. YAML kennt keine Obergrenze für Ganzzahlen, JSON-Zahlen sind IEEE-Doubles, und eine 64-Bit-ID wie 9223372036854775807 kommt als 9223372036854776000 heraus, ohne dass irgendetwas das meldet. Werte dieser Größenordnung sollten in der YAML-Quelle als Zeichenkette quotiert werden, bevor sie hier ankommen.

JSON hat sechs Typen, YAML ein Tag-System. Wo beide auseinanderlaufen, wird etwas abgeflacht. Ein Wert mit dem expliziten Tag !!timestamp wird zu einem Datum und dann zu einer ISO-8601-Zeichenkette, normalisiert auf UTC — ein mit minus fünf Stunden Versatz geschriebener Zeitstempel kommt verschoben und mit Z markiert heraus, der ursprüngliche Versatz ist weg.

Ein !!binary-Wert wird zu Bytes dekodiert und dann als nach Position benanntes Objekt geschrieben — die zwei Bytes von "hi" kommen als {"0":104,"1":105} an. Die Daten sind vollständig da, aber kein Verbraucher wird sie erkennen; ein solches Feld vor der Umwandlung in der YAML als Base64-Text zu kodieren ist der kürzere Weg.

Zwei Fehler stoppen die Umwandlung vollständig. Doppelte Schlüssel in derselben Zuordnung werden abgelehnt — die Meldung nennt die Zeile — was strenger ist als manche YAML-Werkzeuge, aber grundsätzlich richtig: Ein doppelter Schlüssel bedeutet, dass eine der beiden Einstellungen seit ihrem Hinzufügen ignoriert wurde.

Der zweite Fehler ist ein Tabulator zur Einrückung. YAML verbietet das, und der Parser meldet Zeile und Spalte. Beide Fehler sind ein Gefallen: Eine Datei mit einem der beiden Probleme verhält sich schon vorher abhängig davon, welcher Parser sie liest.

Die Ausgabe ist mit zwei Leerzeichen eingerückt und endet mit einem Zeilenumbruch, sodass jq, ein JSON-Schema-Validator oder ein HTTP-Client sie direkt lesen. Validierung ist der stärkste Grund für diesen Umweg: JSON Schema ist ausgereift und weit verbreitet, und eine generierte JSON-Kopie einer Konfiguration gegen ein Schema laufen zu lassen findet Tippfehler in Schlüsselnamen, die ein YAML-Linter — der nur Syntax prüft — durchwinkt.

Ein Ersatz für die YAML-Datei ist das JSON nicht. Kommentare sind weg, Anker sind zu Wiederholungen aufgelöst, und eigene Tags sind stillschweigend verschwunden. Die YAML bleibt die Quelle, das JSON ist die Ansicht darauf.

Parsen und Serialisieren laufen beide als JavaScript in diesem Tab. Eine Konfiguration mit Cluster-Namen, Registry-Adressen oder Zugangsdaten bleibt auf dem eigenen Rechner, und Dateien bis 100 MB werden auf der kostenlosen Stufe angenommen.

Das lässt sich im Netzwerk-Tab des Browsers während der Umwandlung nachprüfen, statt es nur zu behaupten — bei einer Datei, die möglicherweise Geheimnisse enthält, ist das der Unterschied zwischen einer Aussage und einem Beleg.