Dieselben Daten in beiden Formaten
Hier eine kleine Konfiguration in JSON: {"name": "shop", "port": 8080, "debug": false, "hosts": ["a.example.com", "b.example.com"]}. In YAML werden dieselben Daten mit Einrückung statt geschweiften Klammern geschrieben: name: shop in einer Zeile, port: 8080 in der nächsten, debug: false und dann hosts: gefolgt von zwei eingerückten Zeilen, die mit einem Bindestrich beginnen.
Beide werden in jeder Programmiersprache zu genau demselben Objekt geladen. Der Unterschied liegt darin, wie sie geschrieben werden und was jedes Format sonst noch erlaubt.
| JSON | YAML | |
|---|---|---|
| Struktur | Geschweifte und eckige Klammern | Einrückung, auf Wunsch auch Klammern |
| Text | Immer in doppelten Anführungszeichen | Anführungszeichen meist optional |
| Kommentare | Nicht erlaubt | Zeilen, die mit # beginnen |
| Mehrzeiliger Text | Nur mit \n innerhalb eines Strings | Blöcke mit | oder > |
| Teile wiederverwenden | Nicht möglich | Anker (&name) und Aliase (*name) |
| Mehrere Dokumente in einer Datei | Nein | Ja, getrennt durch eine Zeile aus drei Bindestrichen |
| Typischer Einsatz | APIs, Datenaustausch, Browser | Konfiguration: Docker Compose, Kubernetes, CI |
Hier ausprobieren: YAML in JSON
Vollständige Tool-Seite öffnenWarum sich YAML angenehm schreibt
YAML braucht weniger Zeichen. Es gibt keine schließenden Klammern zu zählen, keine Kommas zwischen Einträgen, die man vergessen kann, und um den meisten Text keine Anführungszeichen. Mit Kommentaren kannst du erklären, warum eine Einstellung existiert. Deshalb haben Tools, die Menschen täglich bearbeiten, etwa Docker Compose, Kubernetes, GitHub Actions und Ansible, YAML gewählt.
Anker vermeiden Wiederholungen: Du definierst einen Block einmal mit &defaults und verwendest ihn mit *defaults wieder, oder du fügst ihn mit <<: *defaults in einen anderen Block ein und überschreibst einzelne Schlüssel. Blocktext behält Zeilenumbrüche, so bleiben Skripte und lange Meldungen in der Datei lesbar.
YAML-Fallen, die deine Daten verändern
Die Freiheit, Anführungszeichen wegzulassen, hat ihren Preis: YAML rät den Typ jedes Werts ohne Anführungszeichen, und das Ergebnis ist nicht immer das, was du gemeint hast. Die meisten dieser Probleme verschwinden, wenn Text in Anführungszeichen steht.
- Das Norwegen-Problem: In YAML 1.1, das viele Tools noch nutzen, sind NO, no, yes, on und off Wahrheitswerte. Eine Liste von Ländercodes mit NO für Norwegen wird zu false.
- Versionsnummern: 1.10 ist die Zahl 1.1, und 3.0 kann zu 3 werden. Schreib "1.10", damit es Text bleibt.
- Führende Nullen: Postleitzahlen und Artikelcodes wie 0123 können zu Zahlen werden, und YAML 1.1 liest sie als Oktalzahlen, aus 0123 wird also 83. Das trifft zum Beispiel sächsische Postleitzahlen wie 01067.
- Uhrzeiten: In YAML 1.1 ist 12:30 eine Zahl zur Basis 60, nämlich 750.
- Doppelpunkte und Rauten: Ein Wert, der ": " oder " #" enthält, endet zu früh oder beginnt einen Kommentar. Setz solchen Text in Anführungszeichen.
- Tabs: YAML erlaubt keine Tabs zum Einrücken, und ein Schlüssel, der ein Leerzeichen zu weit eingerückt ist, landet in manchen Editoren ohne jede Fehlermeldung im falschen Block.
Warum JSON für Programme besser ist
JSON hat für jede Sache genau eine Schreibweise und kein Raten: Text steht immer in Anführungszeichen, "NO" bleibt also Text, und 1.10 ist eindeutig eine Zahl. Parser sind klein, schnell und in jeder Sprache verfügbar, und Browser lesen JSON von Haus aus. Das macht JSON zur sichereren Wahl, wenn Daten von Software erzeugt und gelesen werden, etwa bei API-Antworten, Logs, Caches und Datendateien.
Die fehlenden Kommentare sind die häufigste Klage. Manche Tools akzeptieren JSON mit Kommentaren (oft JSONC genannt), aber Standardparser lehnen es ab, daher ist es kein gutes Format für Dateien, die andere Programme lesen müssen.
Sicher zwischen YAML und JSON umwandeln
YAML 1.2 wurde als Obermenge von JSON entworfen, fast jedes JSON-Dokument ist also auch gültiges YAML. Die andere Richtung braucht einen echten Parser, weil YAML-Funktionen aufgelöst werden müssen: Anker und Merge-Keys werden ausgeschrieben, Blocktext wird zu einem String mit \n, und mehrere Dokumente werden zu einer Liste. Kommentare lassen sich nicht übertragen, weil JSON keinen Platz dafür hat.
Wenn du JSON in YAML umwandelst, muss jeder Wert in Anführungszeichen, den ein YAML-Leser falsch verstehen könnte. Der Konverter auf dieser Seite prüft jeden Textwert gegen die Regeln von YAML 1.1 und YAML 1.2 und setzt nur dann Anführungszeichen, wenn es nötig ist, so kommen yes, NO, 0123 und 1.10 unverändert zurück. Das Ergebnis mit Tauschen zurückzuwandeln ist ein schneller Beweis, dass sich nichts verändert hat.
Was solltest du nehmen?
- Nimm YAML für Konfiguration, die Menschen von Hand schreiben und prüfen, vor allem wenn Kommentare helfen.
- Nimm JSON für Daten, die Programme austauschen, speichern oder über das Netzwerk senden.
- Nimm JSON, wenn die Datei von Code erzeugt wird, auch wenn später ein Mensch sie liest.
- Akzeptiert ein Tool beide Formate, wie es viele tun, bleib bei dem Format, das dein Team schon nutzt: Einheitlichkeit zählt mehr als die kleinen Unterschiede.
- Bleibst du bei YAML, setz Textwerte, die wie Zahlen, Datumsangaben oder yes/no aussehen, in Anführungszeichen und prüf Dateien vor dem Deployment mit einem Parser.