Aus {"port": 8080, "hosts": ["web-1", "web-2"], "debug": false} wird in YAML eine Zeile port: 8080, darunter hosts: mit zwei eingerückten Strichen für die beiden Namen, und darunter debug: false. Dieselben Daten, nur ohne Klammern und Kommas — der Grund, warum Konfigurationen seit Jahren in YAML geschrieben werden und nicht in JSON.
In einer Hinsicht ist die Umwandlung geschenkt: YAML ist seit Version 1.2 eine Obermenge von JSON, Ihre Datei ist also, von Randfällen abgesehen, bereits gültiges YAML, ohne dass jemand sie anfasst. Arbeit macht erst die lesbare Form, und die verlangt Entscheidungen — wie mehrzeilige Werte umgebrochen werden, wann eine Zeichenkette Anführungszeichen braucht, wie man ein leeres Objekt hinschreibt. Dieses Werkzeug schreibt Blockstil, setzt Anführungszeichen dort, wo sie die Bedeutung sichern, zählt die Knoten des Dokuments mit und reicht bei ungültiger Eingabe die Meldung des Browser-Parsers durch — mitsamt Position, soweit der Browser sie nennt.
Das Norwegen-Problem und seine Verwandten
In YAML 1.1 sind y, yes, on und no Schreibweisen für Wahrheitswerte. Eine Länderliste mit dem Kürzel NO für Norwegen kommt deshalb in manchen Programmen als false an — der Fall ist unter dem Namen „Norway problem“ bekannt und hat es bis in die Fehlerberichte großer Projekte geschafft. YAML 1.2 hat die Kurzformen aus dem Kern gestrichen, nur lesen etliche verbreitete Bibliotheken bis heute nach 1.1.
Versionsnummern und Kennungen verhalten sich ähnlich: 1.10 gilt dem Leser als Gleitkommazahl und wird zu 1.1, die führende Null in 0755 kann als Oktalzahl durchgehen, 2026-08-25 wird zum Zeitstempel und 22:30 in älteren Lesern zur Zahl zur Basis 60. Wo im JSON eine Zeichenkette steht, setzt dieses Werkzeug darum Anführungszeichen, sobald der Text auch als Zahl, Wahrheitswert, Datum, Uhrzeit oder null gelesen werden könnte. Welche dieser Fallen tatsächlich zuschnappt, hängt an der lesenden Bibliothek — die Anführungszeichen wirken unabhängig davon.
Mehrzeilige Werte und leere Objekte
Für Text mit Zeilenumbrüchen kennt YAML den Blockstil: | behält die Umbrüche, > faltet sie zu Leerzeichen zusammen. Der abschließende Umbruch wird gesondert geregelt — |- schneidet ihn ab, | behält genau einen, |+ behält alle. Mehrzeilige Zeichenketten schreibt dieses Werkzeug als Literalblock und entscheidet zwischen |- und | danach, ob der Wert im JSON auf einen Umbruch endet; der Blockinhalt rückt dabei eine Stufe tiefer ein als sein Schlüssel, denn fest auf zwei Leerzeichen gesetzt stünde er in jeder verschachtelten Datei falsch. Was ein Block nicht darstellen kann — eine Zeile, die auf ein Leerzeichen endet, oder gleich mehrere Umbrüche am Schluss —, landet in Anführungszeichen mit \n.
Leere Objekte und Arrays bleiben in der Klammerschreibweise stehen: {} und []. Das ist keine Nachlässigkeit, sondern notwendig — ein Schlüssel ohne Wert bedeutet in YAML null, nicht „leeres Objekt“, und der Unterschied fällt erst auf, wenn das lesende Programm über null stolpert.
Was erhalten bleibt und was nicht
Die Reihenfolge der Schlüssel übernimmt das Werkzeug unverändert aus dem JSON, sortiert wird nichts — mit einer Ausnahme: Schlüssel, die aussehen wie ganze Zahlen, zieht JavaScript beim Einlesen nach vorn und ordnet sie aufsteigend, aus {"10": …, "2": …} wird also erst 2 und dann 10. Verlassen sollte sich ein Programm auf die Reihenfolge ohnehin nicht: Eine Zuordnung ist nach der YAML-Spezifikation eine ungeordnete Menge, die Reihenfolge ist also für den Menschen und für den Vergleich zweier Dateien da. Doppelte Schlüssel verschwinden schon vor der Umwandlung — beim Einlesen des JSON gewinnt der letzte, ohne Warnung.
Kommentare kann diese Richtung nicht verlieren, weil JSON keine kennt. Für den Rückweg gilt das nicht: Wer YAML in JSON überführt, lässt jedes # und jeden Anker liegen, daran ändert kein Werkzeug etwas. Der zweite Unterschied sind Tabulatoren — YAML verbietet sie zur Einrückung ausdrücklich, weshalb hier nur zwei oder vier Leerzeichen zur Wahl stehen; innerhalb einer Zeichenkette in doppelten Anführungszeichen sind sie erlaubt und werden als \t geschrieben.