Fallstricke beim Konvertieren zwischen JSON und YAML

Auf den ersten Blick wirken JSON und YAML wie zwei Schreibweisen für dieselbe Sache: geschachtelte Objekte, Listen, Schlüssel-Wert-Paare. Und tatsächlich lässt sich jedes JSON-Dokument in gültiges YAML verwandeln, denn JSON ist formal eine Teilmenge von YAML 1.2. Der umgekehrte Weg ist der heikle. YAML kann Dinge ausdrücken, die JSON schlicht nicht kennt, und die automatische Typ-Erkennung von YAML kann Werte still verändern. Wer beide Formate ohne Vorsicht hin- und herkonvertiert, riskiert kaputte Konfigurationen, verschwundene Kommentare und aufgeblähte Dateien.

Dieser Ratgeber zeigt dir, welche Eigenschaften einen Formatwechsel nicht überleben, warum das so ist und wie du trotzdem saubere, verlustarme Ergebnisse bekommst.

Das Grundproblem: nicht 1:1 deckungsgleich

JSON wurde bewusst minimal gehalten. Es kennt genau sechs Wertetypen: Objekt, Array, String, Zahl, Boolean und null. Keine Kommentare, keine Referenzen, keine Datumstypen, keine mehreren Dokumente pro Datei. YAML dagegen ist als menschenfreundliches Format entworfen und bringt eine ganze Reihe Zusatzfeatures mit.

Wenn du von YAML nach JSON konvertierst, muss jedes dieser Zusatzfeatures irgendwie auf das kleinere JSON-Vokabular abgebildet werden. Manches lässt sich sauber übersetzen, anderes geht unwiederbringlich verloren. Und in die Gegenrichtung (JSON nach YAML) lauert die Gefahr eher bei der Typ-Automatik, die YAML beim Wiedereinlesen anwendet. Ein Überblick über die grundlegenden Rollen beider Formate findest du im Ratgeber JSON und YAML im Vergleich.

Kommentare gehen verloren

Der häufigste und schmerzhafteste Verlust. YAML erlaubt Kommentare mit #, und in echten Konfigurationsdateien stehen dort oft die wichtigsten Hinweise: Warum ein Wert gesetzt ist, welche Alternativen es gäbe, wer ihn zuletzt angefasst hat.

# Timeout in Sekunden, hoeher setzen bei langsamer DB
timeout: 30
port: 8080  # Standardport, nicht aendern ohne Firewall-Freigabe

JSON kennt keine Kommentare. Konvertierst du dieses YAML nach JSON, bleibt nur:

{
  "timeout": 30,
  "port": 8080
}

Das gesamte Wissen aus den Kommentaren ist weg. Bei einer reinen Einweg-Konvertierung ist das akzeptabel. Problematisch wird es, wenn jemand JSON bearbeitet und danach zurück nach YAML wandelt: Die Kommentare kehren nicht zurück, denn sie waren nie im JSON gespeichert. Behalte die YAML-Datei deshalb immer als Quelle, wenn Kommentare wichtig sind.

Anchor und Alias werden aufgelöst

YAML kann sich mit Anchor (&name) und Alias (*name) auf bereits definierte Werte beziehen. Damit vermeidest du Wiederholungen:

standard: &standard
  retries: 3
  timeout: 30

dienst_a:
  <<: *standard
  name: A
dienst_b:
  <<: *standard
  name: B

Das ist kompakt und wartbar: Änderst du standard, ändern sich alle abgeleiteten Blöcke mit. JSON kennt keine Referenzen. Beim Konvertieren muss der Parser die Aliasse auflösen und den referenzierten Inhalt an jeder Stelle vollständig ausschreiben:

{
  "standard": { "retries": 3, "timeout": 30 },
  "dienst_a": { "retries": 3, "timeout": 30, "name": "A" },
  "dienst_b": { "retries": 3, "timeout": 30, "name": "B" }
}

Zwei Konsequenzen: Erstens wird aus kompaktem YAML ein deutlich größeres JSON, weil jeder Verweis dupliziert wird. Bei vielen Referenzen kann die Datei um ein Vielfaches wachsen. Zweitens geht die Verbindung verloren: Wandelst du zurück nach YAML, sind aus den Referenzen unabhängige Kopien geworden, die du künftig einzeln pflegen musst. Die DRY-Struktur (Don’t Repeat Yourself) ist dahin.

Ein Randfall am Rande: Rekursive Anchor (ein Wert, der auf sich selbst verweist) lassen sich gar nicht nach JSON übersetzen, weil daraus eine unendlich tiefe Struktur würde. Solche Konstrukte sind selten, führen bei der Konvertierung aber zu einem Fehler statt zu einem Verlust.

Die Norway-Falle und die Boolean-Automatik

Das berüchtigtste YAML-Problem betrifft die automatische Typ-Erkennung. In YAML 1.1 (das viele Parser aus Kompatibilitätsgründen bis heute unterstützen) werden zahlreiche Wörter ohne Anführungszeichen automatisch als Boolean interpretiert: yes, no, true, false, on, off und sogar die einzelnen Buchstaben y und n.

Der Klassiker ist die sogenannte Norway-Falle. Eine Liste von Ländercodes:

laender:
  - DE
  - FR
  - NO

Der ISO-Code für Norwegen ist NO. In einem YAML-1.1-Parser wird NO zu dem Boolean false. Aus deiner Länderliste wird also ["DE", "FR", false]. Solche Fehler fallen oft erst spät auf, weil der Datentyp erst beim Weiterverarbeiten Probleme macht.

Die gleiche Automatik schnappt bei weiteren Werten zu:

• Versionsnummern: version: 1.10 wird als Zahl gelesen und zu 1.1 gekürzt, weil die nachfolgende Null bei einem Float bedeutungslos ist. Die Patch-Version ist verändert.
• Führende Nullen: id: 007 kann je nach Parser als Oktalzahl oder als Integer 7 interpretiert werden, die führenden Nullen verschwinden. PLZ, Artikelnummern und Telefonvorwahlen sind betroffen.
• Sonstige Boolean-Wörter: Ein Schalter feature: off wird zu false, ein Kürzel antwort: y zu true.

Beim Konvertieren nach JSON wird der bereits falsch erkannte Typ mitgenommen. Das JSON enthält dann false statt "NO", und der Fehler wird zementiert. Die einzige zuverlässige Abwehr: Werte, die als Text gemeint sind, in Anführungszeichen setzen.

laender:
  - "DE"
  - "FR"
  - "NO"
version: "1.10"
id: "007"

Ein guter Grund, moderne YAML-1.2-Parser zu bevorzugen: Dort wurde die aggressive Boolean-Liste auf true und false reduziert, NO und on bleiben also Strings. Trotzdem gilt Quoten als sichere Gewohnheit, weil du nie garantieren kannst, welche Parser-Version am anderen Ende läuft. Die grundlegenden Regeln dazu findest du im Ratgeber YAML-Syntax verstehen.

Datumstypen

YAML kann Datums- und Zeitangaben als eigenen Typ erkennen. Ein Wert wie 2026-07-03 wird nicht als String, sondern als Datum interpretiert. JSON kennt keinen Datumstyp, dort ist alles entweder Zahl oder String.

Beim Konvertieren nach JSON wird das Datum meist als String serialisiert, oft im ISO-Format. Das ist an sich unproblematisch. Heikel wird es beim Rückweg: Der String "2026-07-03" kann in YAML erneut als Datum erkannt werden, während "2026-07-03T10:00:00Z" je nach Parser unterschiedlich behandelt wird. Wenn du dir sicher sein willst, dass ein Datum als Text bleibt, quote es explizit.

Zahlengenauigkeit und große Integer

Beide Formate speichern Zahlen als Text, aber die Parser dahinter arbeiten oft mit Fließkomma-Arithmetik (JavaScript etwa kennt nur ein einziges Number-Format nach dem Standard IEEE 754). Ganzzahlen über etwa 9 Billiarden (2 hoch 53) können dabei ungenau werden. Eine 64-Bit-ID wie 9007199254740993 wird eventuell zu 9007199254740992 gerundet.

Dieses Problem gehört streng genommen nicht zum Formatwechsel selbst, sondern zur verarbeitenden Sprache, tritt aber genau beim Parsen und Neuschreiben auf. Wenn du mit großen IDs oder mit Nachkommastellen arbeitest, bei denen jede Ziffer zählt (Geldbeträge, wissenschaftliche Messwerte), speichere sie als String. So bleibt die exakte Ziffernfolge erhalten. Mehr zum grundsätzlichen Aufbau von Werten und Strukturen liest du im Ratgeber JSON-Struktur verstehen.

Reihenfolge der Schlüssel

Weder JSON noch YAML garantieren durch ihre Spezifikation, dass die Reihenfolge der Objektschlüssel erhalten bleibt, denn ein Objekt ist formal eine ungeordnete Menge von Paaren. In der Praxis behalten die meisten guten Parser die Reihenfolge bei, weil das für die Lesbarkeit und für Versionskontrolle (kleinere Diffs) wichtig ist. Verlass dich aber nicht blind darauf: Manche Werkzeuge sortieren Schlüssel alphabetisch um. Wenn die Reihenfolge für dich Bedeutung hat, prüfe das Ergebnis oder wähle ein Werkzeug, das die Reihenfolge nachweislich bewahrt.

Mehrere YAML-Dokumente in einer Datei

YAML erlaubt es, mehrere unabhängige Dokumente in einer Datei zu bündeln, getrennt durch ---:

---
name: erstes
---
name: zweites

Das ist etwa bei Kubernetes-Manifesten üblich. JSON kennt dieses Konzept nicht, eine JSON-Datei enthält immer genau einen Wert an der Wurzel. Beim Konvertieren hast du zwei Möglichkeiten: entweder nur das erste Dokument übernehmen (dann gehen die übrigen verloren) oder alle Dokumente in ein JSON-Array packen. Achte darauf, welche Variante dein Werkzeug wählt, sonst fehlen dir hinterher Daten.

Überblick: Was überlebt den Wechsel?

Eigenschaft	Überlebt Wechsel?	Hinweis
Objekte, Arrays, Strings, Zahlen, Boolean, null	Ja	Der gemeinsame Kern beider Formate
Kommentare (#)	Nein	JSON kennt keine, gehen bei YAML nach JSON verloren
Anchor und Alias	Teilweise	Werden aufgelöst und ausgeschrieben, Datei wird größer
Boolean-Automatik (NO, yes, off)	Riskant	YAML 1.1 wandelt in Boolean, quoten schützt
Versionsnummern wie 1.10	Riskant	Wird als Float zu 1.1 gekürzt, als String quoten
Führende Nullen (007)	Riskant	Verschwinden bei Zahl-Interpretation, als String quoten
Datumstypen	Teilweise	Werden zu String, Rückweg kann sie wieder als Datum lesen
Große Integer / Präzision	Riskant	Parser-Rundung möglich, als String speichern
Schlüsselreihenfolge	Meist	Nicht garantiert, gute Werkzeuge behalten sie
Mehrere Dokumente (---)	Teilweise	JSON hat nur eine Wurzel, als Array bündeln oder Verlust

Wie du sauber konvertierst

Aus den Fallstricken ergeben sich ein paar einfache Regeln:

1. Quote alles, was Text sein soll. Ländercodes, Versionsnummern, IDs mit führenden Nullen, große Zahlen und alle Boolean-ähnlichen Wörter (no, yes, on, off) gehören in Anführungszeichen, wenn sie als String gemeint sind.
2. Bevorzuge YAML 1.2. Die neuere Spezifikation entschärft die Boolean-Automatik erheblich. Prüfe, welche Version dein Parser voreingestellt hat.
3. Behalte die reichere Quelle. Wenn Kommentare oder Anchor wichtig sind, bleibt die YAML-Datei die Quelle der Wahrheit. Nutze JSON nur als Ausgabeformat, nicht als neuen Ausgangspunkt.
4. Prüfe das Ergebnis. Nach jeder Konvertierung ein kurzer Blick auf kritische Werte: Sind Ländercodes noch Strings? Ist die Versionsnummer vollständig? Stimmen große IDs?

Der kostenlose Konverter auf jsonyaml.de hilft dir dabei: Er zeigt Syntaxfehler mit Zeilennummer an, löst Anchor beim Weg nach JSON sauber auf und behält die Reihenfolge deiner Schlüssel bei. Unter der Haube arbeitet die etablierte Bibliothek js-yaml, und die gesamte Umwandlung passiert lokal in deinem Browser, ohne dass deine Daten hochgeladen werden. So kannst du das Ergebnis direkt gegen deine Erwartung prüfen, bevor du es weiterverwendest.

Wer diese Regeln beherzigt, verliert beim Formatwechsel höchstens noch das, was JSON prinzipbedingt nicht kennt (Kommentare und Referenzen), und behält alle Werte unverändert. Das ist der Unterschied zwischen einer verlustarmen Konvertierung und einer kaputten Konfiguration.

Hast du einen Fehler entdeckt oder einen Quellen-Hinweis für uns? Schreib gern an info@akara-solutions.de.