YAML vs. JSON: wann du was nehmen solltest

Du öffnest zwei Konfigurationsdateien mit exakt denselben Einstellungen. Die eine steckt in geschweiften Klammern und Anführungszeichen, die andere liest sich fast wie eine Gliederung. Sie tragen identische Daten, fühlen sich aber völlig anders an. Genau dieser Unterschied, streng gegen lesbar, ist die ganze Geschichte von YAML gegen JSON, und er sagt dir, wann du zu welchem greifen solltest.

TL;DR: JSON und YAML beschreiben dieselben Formen: Maps, Listen und einfache Werte. JSON ist streng, arbeitet mit geschweiften und eckigen Klammern und ist ideal für APIs und Maschine-zu-Maschine-Daten, wo verlässliches Parsen zählt. YAML basiert auf Einrückung, erlaubt Kommentare und ist beim Bearbeiten von Hand deutlich angenehmer, weshalb Konfigurationsdateien es bevorzugen. Jedes YAML lässt sich in JSON umwandeln und zurück. Nimm JSON für den Datenaustausch, YAML für von Menschen geschriebene Konfiguration.

Was sie gemeinsam haben

Beide Formate bilden dieselben drei Bausteine ab: Mappings (Schlüssel-Wert-Paare), Sequenzen (geordnete Listen) und Skalare (einfache Werte wie Text, Zahlen und Booleans). Schachtelt man das, lässt sich fast jede strukturierte Datenform beschreiben. Weil das zugrunde liegende Modell übereinstimmt, sind die beiden inhaltlich austauschbar. Ein Dokument im einen Format lässt sich immer ins andere umschreiben.

YAML formalisiert diese Überschneidung sogar. Die YAML-Spezifikation definiert das Format als Obermenge von JSON, was bedeutet: Eine gültige JSON-Datei ist bereits gültiges YAML. Du kannst JSON direkt in einen YAML-Parser einfügen, und es funktioniert. Der umgekehrte Weg braucht einen Konvertierungsschritt, weil YAML Funktionen hat, die JSON fehlen, aber in keine Richtung gehen Informationen verloren. Deshalb kann ein YAML-zu-JSON-Konverter deine Daten sauber hin und her wandeln: Die Formen sind gleich, nur die Oberflächensyntax ändert sich.

Wenn Leute also fragen, welches Format mehr kann, lautet die ehrliche Antwort: Bei gewöhnlichen Daten sind sie gleichauf. Die Unterschiede liegen in der Ergonomie, nicht darin, was sich ausdrücken lässt.

Wo JSON gewinnt

JSON gewinnt überall dort, wo eine Maschine die Daten liest. Seine Grammatik ist winzig und starr: geschweifte Klammern für Objekte, eckige für Arrays, doppelte Anführungszeichen bei jedem Schlüssel und jeder Zeichenkette, Kommas zwischen den Elementen, sonst nichts. Diese Strenge ist ein Vorteil. Ein Parser hat kaum Mehrdeutigkeit aufzulösen, deshalb parst JSON schnell, verhält sich in allen Sprachen gleich und überrascht selten.

Diese Verlässlichkeit ist der Grund, warum sich APIs darauf festgelegt haben. Wenn ein Server Daten an einen Browser schickt oder ein Dienst einen anderen aufruft, müssen sich beide Seiten sofort über die Bedeutung einig sein, ohne dass ein Mensch einen Fehler bemerken könnte. JSON liefert das. Fast jede Programmiersprache bringt JSON-Unterstützung in ihrer Standardbibliothek mit, und jeder HTTP-Client versteht es ohne zusätzliche Einrichtung.

Der Preis dafür ist Komfort. JSON verbietet Kommentare, du kannst eine Konfigurationsdatei also nicht direkt im Text mit Anmerkungen versehen. Es lehnt auch nachgestellte Kommas ab, also das harmlose Komma nach dem letzten Element einer Liste, worüber Leute beim Bearbeiten von Hand ständig stolpern. Und jede Zeichenkette braucht Anführungszeichen, jeder Schlüssel braucht Anführungszeichen, jede Ebene braucht ihre geschlossenen Klammern. Für eine Maschine ist das nichts. Für einen Menschen, der es von Hand tippt, ist es Reibung.

Wo YAML gewinnt

YAML gewinnt überall dort, wo ein Mensch die Datei schreibt und liest. Es lässt die meiste Zeichensetzung weg: Die Struktur entsteht durch Einrückung statt durch Klammern, Schlüssel kommen meist ohne Anführungszeichen aus, und Elemente trennst du mit Zeilenumbrüchen statt mit Kommas. Das Ergebnis liest sich eher wie eine strukturierte Notiz als wie Code, weshalb YAML bei Konfiguration den Ton angibt.

Das herausragende Merkmal sind Kommentare. YAML lässt dich eine Zeile mit einer Raute beginnen und eine Einstellung direkt daneben erklären, etwas, das Standard-JSON nicht kann. Für eine Datei, die ein Kollege nächsten Monat bearbeitet, ist dieser begleitende Kommentar viel wert. YAML unterstützt außerdem Anker, also eine Möglichkeit, einen Wert einmal zu definieren und wiederzuverwenden, was Wiederholungen in langen Konfigurationen kürzt.

Genau deshalb greift so viel Konfigurations-Tooling zu YAML: Definitionen von CI-Pipelines, Manifeste für Container-Orchestrierung und unzählige App-Einstellungsdateien setzen darauf. Die Leute, die diese Dateien pflegen, sind Menschen, die von Hand bearbeiten und von Kommentaren und einem überschaubaren Layout profitieren. Der Haken: YAML verlangt beim Tippen mehr Sorgfalt, worum es im nächsten Abschnitt geht.

YAMLs Whitespace-Fallstricke

YAMLs Flexibilität hat scharfe Kanten, und die meisten gehen auf zwei Ursachen zurück: Whitespace und übereifriges Raten von Typen. Weil die Struktur von der Einrückung abhängt, tragen die Leerzeichen am Zeilenanfang Bedeutung. Machst du sie falsch, scheitert die Datei entweder am Parsen oder, schlimmer, sie parst in eine andere Form, als du beabsichtigt hast, obwohl sie gut aussieht.

Die wichtigste Whitespace-Regel: Rücke niemals mit Tabs ein. Die YAML-Spezifikation verbietet Tabulatorzeichen zur Einrückung, ein verirrter Tab, der in deinem Editor genauso aussieht wie Leerzeichen, kann also das ganze Dokument zerschießen. Nur Leerzeichen, konsequent, auf jeder Ebene.

Dann ist da noch das Raten von Typen, das das berühmte Norway-Problem hervorbringt. YAML versucht, Typen aus Werten ohne Anführungszeichen abzuleiten, und liest yes, true und on als Booleans. Der Ländercode für Norwegen, NO, wird als der Boolean false geparst statt als der Text, den du gemeint hast. Zahlen mit führenden Nullen, Versionsangaben und Datumswerte können dir auf dieselbe Weise verrutschen. Die Abwehr ist eine einzige Gewohnheit: Setze jeden Skalar, der eine wörtliche Zeichenkette bleiben soll, in Anführungszeichen. Anführungszeichen kosten zwei Zeichen und löschen eine ganze Klasse von Fehlern aus.

JSON umgeht das alles. Seine Strenge sorgt dafür, dass Whitespace nur Dekoration ist und nie Struktur, und jede Zeichenkette ist per Definition in Anführungszeichen, sodass nichts stillschweigend umgedeutet wird.

Wie du dich entscheidest

Die Regel passt in einen Satz: Nimm JSON für den Datenaustausch, YAML für von Menschen geschriebene Konfiguration. Wenn eine Maschine die Daten erzeugt oder verarbeitet, besonders über ein Netzwerk, greif zu JSON und bekomme dessen Tempo, universelle Unterstützung und null Mehrdeutigkeit. Wenn ein Mensch die Datei schreibt und pflegt, greif zu YAML und bekomme Kommentare plus ein lesbares Layout.

Die meisten Teams nutzen am Ende beides, und das ist richtig, nicht etwa unentschlossen. Deine API spricht JSON, weil Maschinen einen strengen Vertrag brauchen. Deine Einstellungen für Deployment und Pipeline liegen in YAML, weil Menschen sie von Hand justieren. Die beiden sind weniger Rivalen als Werkzeuge für unterschiedliche Leser.

Und wenn du zwischen ihnen wechseln musst, läuft die Konvertierung mechanisch ab. Wirf eine YAML-Konfiguration in einen YAML-zu-JSON-Konverter, um ein Tool zu füttern, das nur JSON annimmt, oder gib einen dichten JSON-Block als YAML aus, um ihn leichter zu lesen. Weil sie ein gemeinsames Datenmodell teilen, ist der Hin- und Rückweg verlustfrei. Das Format, das du gerade hast, muss nie das Format sein, an das du gebunden bist.