YAML vs JSON — wann welches, und warum die meisten Teams beide verwenden

Wenn Sie jemals ein Kubernetes-Manifest, einen GitHub-Actions-Workflow oder eine docker-compose-Datei geöffnet haben, haben Sie YAML verwendet. Wenn Sie jemals eine REST-API aufgerufen oder eine Konfigurationsdatei für ein Node.js-Projekt geschrieben haben, haben Sie JSON verwendet. Beides sind Serialisierungsformate. Beide beschreiben dieselben Arten von Datenstrukturen — Maps, Arrays, Strings, Numbers, Booleans, Null. Warum haben wir also zwei davon?

Die kurze Antwort: YAML optimiert für Menschen, JSON optimiert für Maschinen. Die lange Antwort umfasst ein paar Jahrzehnte Entwicklererfahrung, ein paar Sitzungen von Gremien und eine überraschende Anzahl von Randfällen. Lassen Sie uns das durchgehen.

Wofür JSON gut ist

JSON (JavaScript Object Notation) wurde Anfang der 2000er als Payload-Format für AJAX-Anfragen populär. Es war bewusst klein — sechs Werttypen, keine Kommentare, keine abschließenden Kommas, keine Mehrdeutigkeit. Diese Strenge ist seine Superkraft auf dem Draht:

• Parser sind winzig und schnell. JSON.parse ist in jedem Browser und jeder Sprache-Runtime enthalten. Es gibt nichts, worüber man nachdenken muss.
• Fehler sind eindeutig. Wenn JSON kaputt ist, sagt Ihnen der Parser genau, in welcher Zeile und welcher Spalte.
• Maschinen sind sich über Semantik einig. Eine Zahl ist eine Zahl, ein String ist ein String, true ist true. Es gibt keine Debatte “ist yes ein Boolean oder ein String?”.

Deshalb ist JSON die Lingua Franca der APIs. Wenn zwei Dienste kommunizieren, wollen Sie das Format mit den wenigsten Überraschungen.

Wofür YAML gut ist

YAML (YAML Ain’t Markup Language) wurde für von Menschen geschriebene Konfigurationsdateien entworfen. Es hat einen Teil der Strenge von JSON für Lesbarkeit eingetauscht:

• Keine geschweiften Klammern, keine eckigen Klammern. Struktur ist Einrückung. Ein docker-compose.yml liest sich wie eine Liste von oben nach unten.
• Kommentare. Ein # beginnt einen Kommentar. JSON hat keine Kommentar-Syntax — und das Fehlen von Kommentaren ist der häufigste Grund, warum Teams für Konfigurationsdateien von JSON zu YAML wechseln.
• Anker und Referenzen. &anchor und *reference lassen Sie einen Wert einmal definieren und wiederverwenden. JSON hat kein Äquivalent; Sie müssen kopieren und einfügen.
• Mehrzeilige Strings. Literal-Blöcke (|) und gefaltete Blöcke (>) handhaben Fließtext und Code ohne Escape-Gefrickel.

Deshalb dominiert YAML an Orten, an denen Menschen manuell lesen und schreiben: Kubernetes, GitHub Actions, GitLab CI, Ansible-Playbooks, docker-compose, CloudFormation, OpenAPI-Spezifikationen und der Anstieg von AI-Agent-Konfigurationsdateien im Jahr 2025 (.github/agents.yml, MCP-Server-Manifeste, Evaluierungs-Harnische).

Die Asymmetrie

Hier ist das schmutzige Geheimnis: YAML ist eine Obermenge des Datenmodells von JSON. Jede gültige JSON-Datei kann als YAML ausgedrückt werden, aber das Gegenteil gilt nicht. YAML hat Features, die JSON schlicht nicht hat — Kommentare, Anker, Multi-Doc-Dateien, benutzerdefinierte Tags. Sobald Sie YAML mit Ankern schreiben, können Sie es nicht verlustfrei in JSON zurückkonvertieren. Die Anker verschwinden.

Das ist für Werkzeuge wichtig. Wenn Sie eine YAML-Datei mit &defaults *defaults haben, wird die Konvertierung zu JSON entweder die Referenzen expandieren (und still eine größere Datei erzeugen) oder sie fallen lassen (und still eine kleinere Datei erzeugen). Dasselbe gilt für Kommentare. JSON hat keinen Platz für sie.

Wann man welches verwendet

Verwenden Sie JSON, wenn:

• Sie Daten über das Netzwerk senden (APIs, Message Queues, Event-Payloads).
• Die Datei von Code gelesen wird, nicht von Menschen.
• Sie eindeutige Fehlermeldungen von strengen Parseern wollen.
• Sie auf Parse-Geschwindigkeit auf eingeschränkten Geräten optimieren.

Verwenden Sie YAML, wenn:

• Ein Mensch der Hauptautor und Leser der Datei ist.
• Sie Kommentare zur Erklärung der Absicht wollen.
• Sie Konfigurationsbausteine mit Ankern wiederverwenden wollen.
• Die Werkzeuge in Ihrem Bereich es erwarten (Kubernetes, CI usw.).

Die pragmatische Antwort für die meisten Teams: JSON für den Draht, YAML für Konfiguration, beides für Datenaustausch. Im Zweifel: Speichern Sie die kanonische Version in JSON (verlustfrei) und geben Sie YAML für menschlichen Konsum aus (mit Kommentaren und Ankern), wenn das Publikum ein Entwickler ist, der einen Texteditor öffnet.

Häufige Fallstricke beim Konvertieren zwischen beiden

1. Zahlen und Booleans werden in YAML automatisch typisiert. port: 8080 ist eine Zahl. port: "8080" ist ein String. Das Vergessen von Anführungszeichen kann Ihren Typ ändern.
2. Anker und Kommentare fallen in JSON weg. Da gibt es keinen Weg drumherum — das Format hat keinen Platz dafür.
3. YAML null ist mehrdeutig. key: (leerer Wert) ist null. key: null ist auch null. key: "" ist ein leerer String. Drei verschiedene Dinge.
4. Tabs zerstören YAML. Einrückung muss Leerzeichen sein. Tabs sind ein Fehler.
5. YAML 1.1 vs 1.2 vs 1.2.2. YAML 1.1 behandelte yes, no, on, off als Booleans. YAML 1.2 (die Spezifikation, die von js-yaml, PyYAML und den meisten Parseern 2026 verwendet wird) nicht. Das Wartungs-Release 1.2.2 im Jahr 2025 hat ein paar Randfälle rund um Dokument-Ende-Marker und BOM-Handhabung verschärft — die meisten Parser haben die Korrekturen still übernommen. Wenn Sie aus einer Codebasis aus 2018 migrieren, könnte Ihre Konfiguration immer noch auf subtile Weise brechen.

Werkzeuge, die helfen

Wenn Sie zwischen beiden wechseln — und das werden Sie, weil jedes Team beide verwendet — ist ein schneller client-seitiger Konverter Ihr Freund. Die YAML zu JSON und JSON zu YAML-Tools auf DevSpeedTools laufen vollständig in Ihrem Browser, sodass Konfigurationsdateien mit Geheimnissen nie Ihren Computer verlassen. Öffnen Sie DevTools → Network und Sie sehen keine Requests mit Ihren Daten.

Für YAML, das im Laufe der Zeit unordentlich geworden ist, normalisiert der YAML-Formatter die Einrückung auf zwei Leerzeichen und korrigiert inkonsistente Anführungszeichen. Für Dateien, die nicht geparst werden können, zeigt der YAML-Validator Ihnen die genaue Zeile und Spalte jedes Fehlers.

Die Quintessenz: Hören Sie auf, YAML und JSON als konkurrierende Formate zu behandeln. Sie sind sich ergänzend. Das richtige Format hängt davon ab, wer die Datei liest — eine Maschine, oder ein müder Entwickler um 23 Uhr, der herausfinden will, warum sein Deployment kaputt ist.