JSON, TOML, YAML oder CSON: ein Konfigurationsformat wählen

Kurz gesagt: Verwenden Sie JSON für den Maschinenaustausch und wählen Sie TOML oder YAML für von Menschen gepflegte Konfiguration je nach Ökosystem (YAML für Kubernetes und CI, TOML für flache Strukturen oder native Daten); greifen Sie nur dann auf JSONC zurück, wenn Sie unsicher sind, ob der Leser den Dialekt unterstützt.

JSON existiert für Maschinen, die Daten austauschen; eine Konfigurationsdatei wird von Menschen für Menschen geschrieben. Verwechselt man beides, entsteht ein config.json, das keinen Kommentar halten kann und das niemand zu kürzen wagt.

1. Zuerst zwei verschiedene Arten von Dateien

Datenaustausch und Konfiguration verfolgen nicht dasselbe Ziel, auch wenn dieselbe Person oft beides auf derselben Maschine schreibt.

JSON punktet in der linken Spalte fast perfekt: minimale Grammatik, ein Parser in jeder Sprache, und keine Kommentare bedeuten kein Problem „Kommentar ist vom Wert abgedriftet“. In der rechten Spalte ist seine Strenge reine Reibung: keine Kommentare, keine nachfolgenden Kommas, keine Daten, und mehrzeiliger Text muss mit \n in eine Zeile gequetscht werden.

2. Die vier Kandidaten und ihre Syntax

• JSON: definiert durch RFC 8259 und ECMA-404, mit genau sechs Werttypen: Objekt, Array, String, Zahl, Boolean und null. Es ist der De-facto-Austauschstandard und das einzige Format, das keine Auswahlentscheidung braucht.
• TOML: von Tom Preston-Werner geschaffen, v1.0.0 im Januar 2021 veröffentlicht. Das erklärte Ziel ist ein minimales Konfigurationsformat mit offensichtlicher Semantik, das eindeutig auf eine Hashtabelle abbildet. Cargo.toml und pyproject.toml verwenden es standardmäßig.
• YAML: die aktuelle Spezifikation ist 1.2.2. Einrückung drückt Hierarchie aus, und es unterstützt Kommentare, Anker und mehrere Dokumente. Kubernetes-Manifeste, GitHub Actions und Ansible hängen alle davon ab, zum Preis einer großen Spezifikation und Implementierungsunterschieden.
• CSON: CoffeeScript Object Notation, schreibt Konfiguration mit CoffeeScript-Objektliteralen. Atoms config.cson verwendet es. Es unterstützt Kommentare, unquotierte Schlüssel und nachfolgende Kommas, aber sein Ökosystem verließ nie die JavaScript-Welt.

2.1 Fähigkeitsvergleich

Zwei Zellen verdienen einen Hinweis. TOML hat kein null, was der häufigste Fehler bei der Konvertierung von JSON ist. Das „native Datum“-Verhalten von YAML bedeutet, dass ein 1.1-Parser 2026-10-31 automatisch in ein Datumsobjekt verwandelt, sodass der Typ sprachübergreifend driftet.

3. Kommentare: die einzige Schwäche von JSON

Zuerst die Schlussfolgerung: Wird die Datei von Menschen gepflegt und muss erklärt werden, warum ein Wert so ist, verwenden Sie kein Standard-JSON.

Es gibt vier praktische Wege, sortiert nach Eingriffstiefe:

1. Auf JSONC umstellen, also Standard-JSON plus Kommentare und nachfolgende Kommas. VS Codes settings.json und tsconfig.json verwenden es. Der Preis ist, dass der Leser einen kommentarfähigen Parser wie jsonc-parser verwenden muss; einfaches JSON.parse scheitert. Details stehen in JSON5 und JSONC: JSON mit Kommentaren.
2. Ein Begleitdokument pflegen. config.json bleibt maschinenlesbar, während config.md erklärt, was jedes Feld bedeutet und warum es diesen Wert trägt. Beide liegen im selben Verzeichnis und ändern sich im selben Commit.
3. Erklärungen ins Schema legen. Die Schlüsselwörter description und $comment von JSON Schema können Felder dokumentieren, aber Schemas werden selten zusammen mit der Laufzeitkonfiguration ausgeliefert, sodass die Person, die die Konfiguration liest, sie womöglich nie sieht.
4. Zu TOML oder YAML wechseln und dem Format selbst Kommentare überlassen, die jeder Parser versteht.

复制{
  // Fixed at 8080: the frontend build script reads this port for its proxy
  "port": 8080,
  // Disable watching to avoid exhausting inodes in CI
  "watch": false
}

JSONC bleibt ein Dialekt: Die Endung bleibt .json, aber nur manche Werkzeuge verstehen sie. Wenn Daten das Team verlassen oder eine Dienstgrenze überqueren, muss die Linie zwischen JSONC und Standard-JSON dokumentiert sein.

4. Daten und mehrzeilige Strings: TOMLs angestammtes Terrain

TOML erhebt Datum-Zeit zu einem erstklassigen Typ mit vier Varianten: Offset-Datum-Zeit, lokales Datum-Zeit, lokales Datum und lokale Zeit. Mehrzeilige Strings haben eigene Syntax, die Zeilenumbrüche bewahrt:

复制title = "json-toolkit"
created = 2026-10-31T09:00:00+08:00
description = """
A JSON toolkit for developers.
Every operation runs locally in the browser.
"""

Dieselben Informationen in JSON müssen das Datum zu einem String herabstufen und die Zeilenumbrüche escapen:

复制{
  "title": "json-toolkit",
  "created": "2026-10-31T09:00:00+08:00",
  "description": "A JSON toolkit for developers.\nEvery operation runs locally in the browser."
}

In JSON ist "created" nur ein String, der zufällig wie ein Datum aussieht, die Typinformation muss also in einem Feldvertrag leben: beide Seiten müssen vereinbaren, dass das Feld immer RFC 3339 ist. TOML gibt dem Parser ein tatsächliches Datumsobjekt, ohne mündliche Absprache.

YAML kann auch mehrzeiligen Text halten, aber die beiden Blockstile bedeuten Unterschiedliches: | bewahrt Zeilenumbrüche, während > sie zu Leerzeichen faltet. Wählt man den falschen, kollabiert eine Adresse oder ein SQL-Statement in eine einzige Zeile – ein im Review sehr schwer zu findender Fehler.

5. Zahlen: der am meisten übersehene Unterschied

Die JSON-Spezifikation setzt keine Grenze für die numerische Präzision, aber RFC 8259 warnt auch, dass Interoperabilität am sichersten ist, wenn Zahlen als IEEE-754-Doubles behandelt werden. In JavaScript verlieren Ganzzahlen oberhalb von 2^53 - 1 stillschweigend Präzision:

复制JSON.parse('{"id":9007199254740993}').id
// 9007199254740992: the last digit is gone

TOML verlangt, Signed-64-Bit-Ganzzahlen verlustfrei zu behandeln und lieber einen Fehler zu werfen als stillschweigend abzuschneiden; Floats folgen binary64 und dürfen auch inf oder nan sein. YAML 1.1 trägt eine ältere Last: 1:30 wird als 90 geparst (Sexagesimal), und Booleans akzeptieren yes, no, on und off. Daher das klassische „Norwegen-Problem“, bei dem der Ländercode NO zu false wird.

Verlassen Sie sich bei Geldbeträgen in keinem dieser Formate auf Gleitkommazahlen: Verwenden Sie ganzzahlige kleinste Einheiten, Strings oder einen Dezimaltyp der Datenbank. Formatierung und Präzision werden ausführlicher in den Grenzen der Konvertierung von JSON, YAML und XML behandelt.

6. Tabellen und Verschachtelung: TOMLs harte Grenzen

TOML drückt Verschachtelung mit Tabellen und Arrays von Tabellen aus:

复制[server]
port = 8080

[[routes]]
path = "/parse"
method = "POST"

[[routes]]
path = "/minify"
method = "POST"

Es hat zwei harte Grenzen, die man vor dem Konvertieren kennen muss:

• Die Wurzel eines TOML-Dokuments ist eine Tabelle, ein JSON-Dokument mit einem Array auf oberster Ebene (etwa [1, 2, 3]) hat also keine zulässige TOML-Darstellung; es muss als {"items": [...]} verpackt werden;
• TOML hat kein null, ein JSON-null-Feld muss also entweder entfallen oder durch einen leeren String oder einen Sentinel-Wert ersetzt werden, wobei die Semantik auf den Konsumenten abgewälzt wird.

YAML ist das Gegenteil: Die Verschachtelungstiefe ist unbegrenzt, und Anker plus Merge-Schlüssel können Fragmente wiederverwenden:

复制defaults: &defaults
  retries: 3
  timeoutMs: 5000

server:
  <<: *defaults
  port: 8080

Anker sind eine reine YAML-Fähigkeit und ein garantierter Verlust bei der Konvertierung: JSON hat keine Referenzsyntax, die expandierte Datei wächst also, und nichts hält fest, dass die beiden Abschnitte einst dieselbe Konfiguration waren.

7. Auswahl nach Szenario

Eine Faustregel: Lassen Sie das Ökosystem das Konfigurationsformat wählen, nicht persönliche Vorlieben. Rust schreiben heißt Cargo.toml, auf Kubernetes deployen heißt YAML, und eine VS-Code-Erweiterung bauen heißt JSONC. Nur in einem neuen Projekt ohne Ökosystemzwang ist „was schreibt sich schöner“ eine echte Frage.

8. Konvertierungsgrenzen

Konvertierungswerkzeuge garantieren die Werte, nie die Kommentare. Entwerfen Sie also keine Zweiweg-Pipeline, in der „JSON die Quelle und YAML ein Build-Artefakt ist“. Entweder nur in eine Richtung generieren oder eine einzige Quelldatei pflegen.

9. Checkliste

• [ ] Dokumentieren, welche Dateitypen welches Format verwenden, und die erlaubten Dialekte auflisten;
• [ ] Für von Menschen gepflegte Konfiguration TOML oder YAML bevorzugen, JSON für den Maschinenaustausch;
• [ ] Daten in JSON als RFC-3339-Strings speichern und das Format im Schema markieren;
• [ ] Geldbeträge und Ganzzahlen oberhalb von 2^53 als Strings oder kleinste Einheiten darstellen, nie als Floats;
• [ ] Jedes Format in CI mit seinem eigenen Parser validieren, YAML nie mit JSON.parse;
• [ ] Formate nur in eine Richtung migrieren und die alte Datei löschen, damit beide nicht auseinanderdriften.

FAQ

Warum scheitert die Konvertierung von JSON nach TOML bei manchen Feldern?

TOML hat kein null, und die Wurzel eines TOML-Dokuments ist eine Tabelle, ein JSON-null-Feld muss also entfallen oder durch einen leeren String oder Sentinel ersetzt werden, und ein Array auf oberster Ebene muss als {"items": [...]} verpackt werden. Kommentare, Datumstypen und inf/nan gehen auch in die entgegengesetzte Richtung verloren, weshalb die Konvertierung einbahnig sein sollte.

Sollte ich zwei Konfigurationsdateien in verschiedenen Formaten pflegen?

Nein. Konvertierungswerkzeuge garantieren die Werte, aber nie die Kommentare, eine Pipeline, in der „JSON die Quelle und YAML ein Build-Artefakt ist“, driftet also auseinander. Entweder nur in eine Richtung generieren oder eine einzige Quelldatei pflegen und die alte nach der Migration löschen.

Wie füge ich einer JSON-Konfigurationsdatei Kommentare hinzu?

Standard-JSON kennt keine Kommentare. Sie können auf JSONC umstellen (den VS-Code-Dialekt, gelesen mit jsonc-parser), ein Begleitdokument pflegen, das jedes Feld erklärt, oder zu TOML oder YAML wechseln. An andere Systeme gesendete Dateien sollten Standard-JSON bleiben, mit Erklärungen in der Dokumentation oder einem Schema.

Ist TOML oder YAML besser für Anwendungskonfiguration?

Wählen Sie TOML, wenn die Struktur flach ist, überwiegend aus Schlüssel-Wert-Paaren besteht und native Daten zählen; seine Semantik ist vorhersehbarer und die Parserunterschiede sind kleiner. Wählen Sie YAML, wenn Sie tiefe Verschachtelung, mehrere Dokumente, Ankerwiederverwendung brauchen oder das Zielökosystem YAML-first ist, etwa Kubernetes oder CI. Beide unterstützen Kommentare, der echte Unterschied liegt also in struktureller Komplexität und Ökosystembindung.

Warum wird NO in YAML zu false?

YAML 1.1 behandelt yes, no, on, off, y und n als Booleans, der Ländercode NO für Norwegen wird also als false geparst. Das ist das „Norwegen-Problem“. Vermeiden Sie es, indem Sie eine Implementierung nach YAML 1.2 verwenden oder jeden String quotieren, der missverstanden werden könnte.

Lohnt sich CSON noch?

Für neue Projekte nicht. CSON hängt vom CoffeeScript-Ökosystem ab, hat wenige gepflegte Werkzeuge und begrenzte Editor- und CI-Unterstützung; nachdem Atom nicht mehr gepflegt wird, sind seine Anwendungsfälle weiter geschrumpft. Hat ein Projekt bereits CSON-Konfiguration, planen Sie eine einmalige Migration nach JSON, TOML oder YAML, statt mehr davon hinzuzufügen.