YAML vs. JSON: Unterschiede, Beispiele und wann was passt

YAML vs. JSON, kurz erklärt: Beide sind Textformate für dieselben Datenarten (Objekte, Listen, Strings, Zahlen, Booleans und null). JSON ist strikt, nutzt geschweifte Klammern und Anführungszeichen und ist der Standard für Web-APIs. YAML setzt auf Einrückung, erlaubt Kommentare, Anker und mehrere Dokumente pro Datei und ist für Konfigurationen beliebt. YAML 1.2 ist fast eine Obermenge von JSON.

Kostenlos ausprobieren: YAML zu JSON Konverter Kostenlos und ohne Anmeldung nutzbar.

JSON (JavaScript Object Notation, definiert in RFC 8259) wurde für den Datenaustausch zwischen Programmen entworfen. Was ist YAML also? Der Name steht für „YAML Ain't Markup Language“, und das Format wurde dafür entworfen, dass Menschen Daten von Hand lesen und bearbeiten. Dieser Leitfaden zeigt dieselben Daten in beiden Formaten, vergleicht sie und behandelt die Stolperfallen beider Formate. Um zu sehen, wie eine Datei im jeweils anderen Format aussieht, fügen Sie sie in den kostenlosen YAML-zu-JSON-Konverter oder den JSON-zu-YAML-Konverter ein.

Dieselben Daten in JSON und YAML

Hier eine kleine Anwendungskonfiguration in JSON:

{
  "name": "web-app",
  "version": "2.4.1",
  "replicas": 3,
  "debug": false,
  "database": {
    "host": "db.example.com",
    "port": 5432
  },
  "features": ["login", "search"],
  "maintainer": null
}

Und dieselben Daten in YAML, dazu ein Kommentar, den JSON nicht aufnehmen kann:

# Settings for the web app
name: web-app
version: 2.4.1
replicas: 3
debug: false
database:
  host: db.example.com
  port: 5432
features:
  - login
  - search
maintainer: null

Beide werden zu genau demselben Objekt geparst. JSON kennzeichnet die Struktur mit {}, [], Kommas und Anführungszeichen; YAML mit Einrückung, key: value-Paaren und - für Listeneinträge. Die meisten Strings brauchen in YAML überhaupt keine Anführungszeichen, weshalb es sich eher wie eine Einstellungsdatei liest als wie Code.

YAML vs. JSON: die wichtigsten Unterschiede

JSON YAML
Struktur Geschweifte und eckige Klammern, Kommas Einrückung (nur Leerzeichen)
Kommentare Nicht erlaubt # comment
Strings Immer in doppelten Anführungszeichen Meist ohne Anführungszeichen; bei Bedarf 'single' oder "double"
Datentypen Objekt, Array, String, Zahl, Boolean, null Dieselben, dazu optionale Tags, Zeitstempel in manchen Schemas und eigene Typen
Wiederverwendung Keine Anker &, Aliase * und Merge-Keys <<
Mehrere Dokumente pro Datei Nein (ein Wert pro Datei) Ja, getrennt durch ---
Mehrzeiliger Text Nur mit \n-Escapes Blockskalare | und >
Parsen Kleine, strikte Grammatik; in Browser und viele Standardbibliotheken eingebaut Umfangreichere Grammatik; meist über eine Drittanbieter-Bibliothek
Typische Einsatzzwecke REST-APIs, package.json, Logs, Daten, die zwischen Programmen ausgetauscht werden Kubernetes-Manifeste, Workflows für GitHub Actions, Docker Compose, Ansible

Manche Formate akzeptieren beides: OpenAPI-Beschreibungen lassen sich in beiden Formaten schreiben, und kubectl apply liest JSON-Manifeste ebenso wie YAML-Manifeste. Generell gilt: JSON gewinnt, wenn Programme die Daten schreiben und lesen; YAML gewinnt, wenn Menschen sie von Hand pflegen und Kommentare brauchen.

Ist YAML eine Obermenge von JSON?

Fast. Die YAML-1.2-Spezifikation (2009) hatte das Ziel, YAML zu einer echten Obermenge von JSON zu machen, und in der Praxis liest ein YAML-1.2-Parser nahezu jedes JSON-Dokument und liefert dieselben Daten zurück. Zwei Einschränkungen:

Umgekehrt gilt das nicht: Das meiste YAML ist kein gültiges JSON.

YAML-Stolperfallen, die Sie kennen sollten

Das Norwegen-Problem (Norway problem): NO wird zu false

In YAML 1.1 sind die Wörter yes, no, on und off ohne Anführungszeichen (kleingeschrieben, mit großem Anfangsbuchstaben oder in Großbuchstaben) Booleans, genau wie true und false. Diese Liste von Ländercodes

countries:
  - GB
  - NO
  - SE

wird daher in einem YAML-1.1-Parser wie PyYAML als ["GB", false, "SE"] geladen. Dieselbe Regel macht den Schlüssel on: eines Workflows für GitHub Actions zum Boolean True, wenn Sie die Datei mit PyYAML laden. Das Core-Schema von YAML 1.2 hat das behoben: Nur true und false (auch als True oder TRUE geschrieben) sind Booleans, ein 1.2-Parser behält NO also als String. Da Sie selten beeinflussen können, welcher Parser Ihre Datei liest, ist es eine sichere Gewohnheit, solche Werte in Anführungszeichen zu setzen: - "NO".

Zahlen, die keine Zahlen sein sollen

Tabs und bedeutungstragende Leerzeichen

Die YAML-Spezifikation verbietet Tabulatorzeichen zur Einrückung, ein Tab am Zeilenanfang ist also ein Syntaxfehler und keine Stilfrage. Die Einrückung trägt außerdem Bedeutung: Verschieben Sie einen Schlüssel um zwei Leerzeichen nach links, landet er in einem anderen übergeordneten Objekt – und die Datei kann dabei vollkommen gültig bleiben, bedeutet aber etwas anderes.

Mehrzeilige Strings: | und >

Ein Literal-Block (|) behält Zeilenumbrüche bei; ein gefalteter Block (>) verbindet Zeilen mit Leerzeichen:

literal: |
  Line one
  Line two
folded: >
  This long sentence is
  folded into one line.

literal wird zu "Line one\nLine two\n" und folded zu "This long sentence is folded into one line.\n". Beide behalten einen abschließenden Zeilenumbruch; mit |- oder >- entfernen Sie ihn.

Anker, Aliase und Merge-Keys

YAML kann einen Block einmal definieren und wiederverwenden:

defaults: &defaults
  adapter: postgres
  port: 5432
production:
  <<: *defaults
  host: db.example.com

&defaults benennt den Block, *defaults verweist darauf, und << übernimmt seine Schlüssel, sodass production am Ende adapter, port und host enthält. JSON hat kein Gegenstück: Bei der Umwandlung in JSON werden die Werte an jede Stelle kopiert, an der sie verwendet werden. Merge-Keys stammen aus YAML 1.1 und gehören nicht zum Core-Schema von 1.2, werden aber von den meisten verbreiteten Parsern weiterhin unterstützt.

JSON-Stolperfallen, die Sie kennen sollten

JSON ist strikt, und drei Regeln verursachen die meisten Fehler:

Diese Datei scheitert deshalb an JSON.parse:

{
  // port for local development
  'port': 8080,
  "tags": ["api", "v2",],
}

Für handgeschriebene Dateien gibt es gelockerte Varianten: JSONC („JSON with comments“) wird von den Einstellungen in VS Code und von tsconfig.json verwendet, und JSON5 erlaubt zusätzlich einfache Anführungszeichen, Schlüssel ohne Anführungszeichen und nachgestellte Kommas. Keine der beiden wird von einem Standard-JSON-Parser akzeptiert. Der JSON-Formatierer nimmt JSON5-Eingaben an, kennzeichnet sie mit „Gültiges JSON5 — in striktes JSON umgewandelt“ und gibt Ihnen Standard-JSON zurück.

.yaml vs. .yml

YAML vs. YML ist keine Formatfrage: Beide Endungen bezeichnen dasselbe Format, und Parsern ist es egal, welche Sie verwenden. RFC 9512, der 2024 den Medientyp application/yaml registriert hat, nennt .yaml die bevorzugte Endung und hält fest, dass .yml weiterhin verwendet wird. Auch die FAQ des YAML-Projekts empfahl .yaml, und Docker Compose sucht nach compose.yaml, bevor es nach compose.yml sucht. GitHub Actions akzeptiert in .github/workflows beide Endungen. Legen Sie sich pro Projekt auf eine fest und führen Sie config.yaml und config.yml nicht nebeneinander.

Sicherheit: nicht vertrauenswürdiges YAML sicher laden

Vollständige YAML-Loader können anhand von Tags sprachspezifische Objekte erzeugen. In Python kann yaml.load(data, Loader=yaml.UnsafeLoader) beliebige Python-Objekte anlegen und mit einer präparierten Datei Code ausführen. Verwenden Sie für Dateien, die Sie nicht selbst geschrieben haben, immer yaml.safe_load(); es erzeugt nur einfache Dicts, Listen, Strings, Zahlen, Booleans und null. Seit PyYAML 6.0 verweigert yaml.load() ohne explizit angegebenen Loader den Dienst. Vorsicht ist auch bei tief verschachtelten Aliasen geboten („Billion Laughs“-Dateien), die sich zu riesigen Strukturen aufblähen. JSON kennt weder Tags noch Aliase, daher liefern JSON.parse und Pythons json.loads immer nur einfache Daten.

Zwischen YAML und JSON konvertieren

Beide Konverter laufen vollständig in Ihrem Browser und nutzen die Open-Source-Bibliothek yaml für JavaScript.

Der YAML-zu-JSON-Konverter parst YAML 1.2, löst Anker und Aliase auf, wendet <<-Merge-Keys an und macht aus einer Datei mit mehreren ----Dokumenten ein JSON-Array. Sie können 2, 3 (Standard) oder 4 Leerzeichen, Tabs oder eine minifizierte Ausgabe wählen, Schlüssel alphabetisch sortieren und das Ergebnis als converted.json herunterladen. Syntaxfehler, etwa ein Tab zur Einrückung, werden mit Zeile und Spalte angezeigt. Kommentare gehen verloren, weil JSON sie nicht speichern kann.

Der JSON-zu-YAML-Konverter liest Standard-JSON und JSON5; Kommentare und nachgestellte Kommas in der Eingabe werden also akzeptiert, aber nicht übernommen. Er schreibt YAML mit zwei Leerzeichen Einrückung und hat keine Optionen. Die Ausgabe folgt YAML 1.2: Strings wie "0755" und "true" werden in Anführungszeichen gesetzt, NO, yes oder on dagegen nicht, weil sie in 1.2 gewöhnliche Strings sind. Wenn ein YAML-1.1-Werkzeug wie PyYAML die Datei lesen soll, setzen Sie diese Werte selbst in Anführungszeichen.

Auf der Kommandozeile konvertiert yq von Mike Farah in beide Richtungen, und jq validiert JSON und gibt es formatiert aus:

yq -o json config.yaml
yq -P -oy config.json
jq . config.json

Wann Sie YAML verwenden sollten und wann JSON

Die Entscheidung JSON vs. YAML hängt meist davon ab, wer die Datei schreibt:

Wenn Sie sich für YAML entscheiden, halten Sie es langweilig: zwei Leerzeichen Einrückung, Anführungszeichen um alles, was als Boolean oder Zahl gelesen werden könnte, und ein Linter wie yamllint in der CI.

FAQ

Ist YAML besser als JSON?

Keines von beiden ist grundsätzlich besser. JSON ist einfacher und strikter und damit die sicherere Wahl für Daten, die zwischen Programmen ausgetauscht werden. YAML ist für Menschen leichter zu lesen und zu bearbeiten und unterstützt Kommentare – deshalb nutzen es so viele Konfigurationsdateien.

Kann ich JSON in einer YAML-Datei verwenden?

Ja. Der Flow-Stil von YAML verwendet dieselben Klammern wie JSON, daher funktionieren ports: [80, 443] oder db: {"host": "localhost"} innerhalb einer YAML-Datei, und ein YAML-1.2-Parser akzeptiert nahezu jedes vollständige JSON-Dokument. Die wichtigste Ausnahme sind doppelte Schlüssel.

Kann JSON Kommentare enthalten?

Nicht in Standard-JSON: RFC 8259 kennt keine Kommentarsyntax, und JSON.parse scheitert an // oder /* */. Manche Werkzeuge akzeptieren JSONC oder JSON5, die Kommentare erlauben, aber Sie müssen die Kommentare entfernen, bevor Sie die Datei an einen strikten Parser übergeben.

Was ist der Unterschied zwischen YAML und YML?

Inhaltlich keiner: .yaml und .yml sind zwei Dateiendungen für dasselbe Format. RFC 9512 nennt .yaml als bevorzugte Endung, aber YAML-Parsern ist die Endung egal.

Warum macht YAML aus NO oder on false oder true?

Weil YAML 1.1 yes, no, on und off als Booleans behandelt. YAML 1.2 behandelt nur true und false als Booleans, aber viele Parser, darunter PyYAML, verwenden noch die Regeln von 1.1. Setzen Sie solche Werte in Anführungszeichen, zum Beispiel country: "NO", dann liest jeder Parser sie als Strings.

Kostenlos ausprobieren: YAML zu JSON Konverter Kostenlos und ohne Anmeldung nutzbar.