TOML gegen YAML gegen JSON — Konfigurationsformate nach der Anzahl an Ärger, die sie Ihnen verursachen

Jeder Projekt führt schließlich dazu, eine Konfigurationsform zu wählen. YAML ist überall. JSON ist älter als einige deiner Kollegen. TOML erschien kürzlich mit der Behauptung: „Tatsächlich wurde ich für diese Aufgabe entwickelt.“ Alle drei werden dich schließlich verraten. Die Verräther sind nur unterschiedlich.

Hier ist eine direkte Vergleich – gleiche Konfiguration, drei Formate – gefolgt von genau dem Zeitpunkt, an dem jede einzelne Form deine Lebensentscheidungen bereuen wird.

Dies ist kein YAML-Bugbericht. Es ist eine Rahmenbedingung für die Entscheidung, die Sie kurz vorher treffen werden: YAML, JSON oder TOML für Ihre nächste Konfigurationsdatei? Jede dieser Formate hat echte Abwägungen, und die Antwort „Verwenden Sie einfach das, was die Ecosystem verwendet“ gilt nicht immer.

Eine grundlegende Webapp-Konfiguration: Name, Port, Debug-Flag, Versionszeichen, Datenbankeinstellungen, erlaubte Ursprünge. Nicht exotisch. Hier beginnen die Unterschiede der Formate.

TOML

# App configuration
[app]
name = "my-app"
port = 3000
debug = false
version = "1.2.3"
allowed_origins = ["https://example.com", "https://api.example.com"]

[database]
host = "localhost"
port = 5432
name = "mydb"

YAML

# App configuration
app:
  name: my-app
  port: 3000
  debug: false
  version: "1.2.3"
  allowed_origins:
    - https://example.com
    - https://api.example.com

database:
  host: localhost
  port: 5432
  name: mydb

JSON

{
  "app": {
    "name": "my-app",
    "port": 3000,
    "debug": false,
    "version": "1.2.3",
    "allowed_origins": [
      "https://example.com",
      "https://api.example.com"
    ]
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb"
  }
}

Überblick

Besonderheit	TOML	YAML	JSON
Kommentare	✅ Ja	✅ Ja	❌ Nein
Typeninferenz	Explizit	Aggressiv (oft falsch)	Explizit
Arrays	= ["a", "b"]	- item oder inline	["a", "b"]
Kommas am Ende	N / A	N / A	❌ Illegal
Tief verknüpfte Konfigurationen	Wird schnell umfangreich	Lesbar, aber nicht perfekt	Umfangreich, aber unmissverständlich
Stabilität der Spezifikation	TOML 1.0 (2021, stabil)	1.1 vs. 1.2 – Parserchaos	Stabil
Null-Unterstützung	❌ Keine Null-Typen	✅ Ja (~ oder null)	✅ Ja (null)
Gewöhnlicher Gebrauch	Cargo.toml, pyproject.toml	GitHub Actions, k8s, Docker	package.json, tsconfig.json

YAML: Am Lesbarsten, bis es nicht mehr ist

YAML sieht in Präsentationen toll aus. Eine flache Konfiguration liest fast wie Prosa. Die Probleme beginnen, wenn man eine der Randfälle erreicht – und zu diesem Zeitpunkt ist die Konfigurationsdatei bereits Träger von Infrastruktur.

Das norwegische Problem

In YAML 1.1 – die meisten Parser verwenden dies standardmäßig – sind diese Werte alle Boolesche Werte: y, n, yes, no, on, off, true, false. So country: NO wird geparsed als country: false. Dies ist der echte Grund dafür, dass es das „Norwegische Problem“ heißen. NO– das ISO-Landkennzeichen Norwegens ist no oder yes . PyYAML hat dies in Version 6.0 (2022 veröffentlicht) behoben. SnakeYAML (benutzt von vielen Java-Tools) hat es noch nicht vollständig behoben. Prüfe deinen Parser, bevor du unbehandelte

in Konfigurationswerten verwendest.

Typeninferenz, die falsch spekuliert port: 8080 Ungequerte Werte in YAML werden typenspezifisch umgewandelt. version: 1.10 wird zu einer Ganzzahl. 1.1 – mathematisch gleich, semantisch falsch. Vergiss, einen Versionsstring zu zitieren, und du wirst zehn Minuten lang verlieren, warum deine App denkt, sie läuft auf v1.1 statt v1.10. Die Lösung ist langweilig: Zitieren Sie alles, was ein String bleiben sollte. Aber YAML zwingt Sie nicht dazu, also tut es es nicht.

Einrückung ist belastend

Tabs sind in YAML illegal – nicht empfohlen, illegal. Mischung aus zwei- und vier-Whitespace-Einrückung innerhalb einer Datei führt zu einem Parse-Fehler, der oft auf die falsche Zeile zeigt. GitHub Actions ist hier der schärfste Punkt: Eine falsch eingerückte run: Block führt zum Laufzeitfehler, nicht zum Parsenfehler, weil Workflow-Runner nur Syntax validieren, nicht die Struktur der Schritte. Du erhältst „unexpected value“ aus einer CI-Aufgabe mit keiner Hinweise auf den betroffenen Schritt, und du verbrichst 20 Minuten, indem du Debug-Ausgabe hinzufügst, bevor du erkennst, dass das Problem eine zwei-Whitespace-Einrückung war, die vier erforderte.

Wenn deine YAML-Datei ein Durcheinander aus ungleichmäßigen Einrückungen ist, wird die YAML-Formatter diese vor der Debugging-Phase normalisieren.

TOML: Die Format, das tatsächlich über Konfiguration nachgedacht hat

Tom Preston-Werner (Mitgründer von GitHub) entwickelte TOML, weil er sich langweilige INI-ähnliche Konfigurationen mit unvorhersehbarem Verhalten und YAML-Konfigurationen, die ihn überraschten, langweilig fühlte. TOML 1.0 erschien im Januar 2021 nach Jahren von Revisionsarbeiten. Es ist heute das Standardformat für Rust-Projekte (Cargo.toml), Python-Pakete (pyproject.toml) und Hugo-Websites. Die Spezifikation ist stabil, die Parser sind konsistent und das Typensystem tut genau das, was du erwartest.

Was es richtig macht

• Keine überraschenden Typumwandlungen. version = "1.10" ist immer ein String. port = 3000 ist immer eine Ganzzahl. Was du schreibst, ist genau das, was du erhältst.
• Kommentare funktionieren genau wie du es erwartest (# bis zum Ende der Zeile), im Gegensatz zu JSON.
• Flache bis mittelgradig verknüpfte Konfigurationen sind tatsächlich lesbar, im Gegensatz zu tief verknüpften JSON-Konfigurationen.

Die Array-of-Tables-Syntax

Das Hauptproblem von TOML ist seine Array-of-Tables-Syntax. Wenn du ein Array von Objekten brauchst – zum Beispiel mehrere Datenbankverbindungen – sieht die Notation so aus:

[[databases]]
name = "primary"
host = "db1.example.com"

[[databases]]
name = "replica"
host = "db2.example.com"

Jede [[double bracket]] Abschnitt ist ein Element im databases Array. Es funktioniert. Es ist unmissverständlich. Aber jeder Entwickler, der ein TOML-Datei zum ersten Mal öffnet, fragt: „Ist das INI?“ – weil es so aussehen könnte. Diese Unbekanntschaft hat einen echten Kosten, wenn du neue Mitwirkende einwebst, die noch nie TOML gesehen haben.

TOML hat auch kein null Typ – absichtlich. Wenn dein Schema „Null“ verwendet, um „ein Schlüssel ist vorhanden, aber explizit nicht gesetzt“ zu bedeuten, musst du das anders modellieren (den Schlüssel ganz zu entfernen oder einen Sentinellwert zu verwenden). Und tief verknüpfte Konfigurationen werden schnell umfangreich: TOML hat kein YAML-Anker-/Alias-System zur Wiederholung von Unterstrukturen, weshalb es viele Kopieren und Einfügen gibt, wenn deine Konfiguration wiederholte Strukturen hat.

Der TOML-Formatter ist nützlich, wenn du versuchst, eine TOML-Datei, die organisch gewachsen ist, zu bereinigen.

JSON: Das, was du kennst

JSON wurde für Datenwechsel – Maschinen miteinander kommunizieren – entwickelt, nicht für Menschen, die Konfigurationsdateien schreiben. Es wurde schließlich zum Konfigurationsformat, weil jede Sprache bereits einen JSON-Parser hatte, und diese Bequemlichkeit gewann. Jetzt haben wir package.json, tsconfig.json, .eslintrc.json und etwa 40 andere JSON-Konfigurationen in jedem JavaScript-Projekt, die alle von Hand bearbeitet werden.

Keine Kommentare. Noch immer.

Douglas Crockford entfernte Kommentare aus JSON absichtlich im Jahr 2012 – er fürchtete, dass Entwickler sie als Parsing-Anweisungen verwenden würden (ähnlich wie IE-Conditionals). Das Internet hat seitdem täglich darüber geklagt. Die Workarounds, die Menschen verwenden:

• JSONC – JSON mit Kommentaren. VS Code verwendet es für settings.json und launch.json. Nicht parsbar durch Standard-JSON-Parsers. Nicht standardkonform.
• JSON5 – fügt Kommentare, Endkommas, ungezogene Schlüssel, mehrzeilige Zeichenketten hinzu. Hat eine Spezifikation und einen separaten Parser. Babel verwendet es für Konfigurationen. Ist immer noch kein Standard-JSON.
• A "_comment" key – ein String-Feld, das deinen Kommentarinhalt enthält. Funktioniert. Sieht lächerlich aus. Eindringt in deine Datenstruktur.

Nachgestellte Kommas

Auch illegal. Füge ein Endkomma nach dem letzten Element in einem Array oder Objekt hinzu und JSON.parse wirft SyntaxError: Unexpected token } – informiert dich über ein Problem, aber nicht, wo das falsche Komma steht. Dies ist die häufigste JSON-Parsfehler in von Menschen geschriebenen Konfigurationsdateien, und es tritt auf, weil alle anderen modernen Sprachen (JavaScript-Arrays, Python-Listen, Rust-Enums) Endkommas erlauben und Menschen JSON von Hand mit denselben Gewohnheiten schreiben.

Was JSON richtig macht

Das Typensystem ist eindeutig und universell. Jeder JSON-Parser in jeder Sprache stimmt darüber ein, was true, 1, "1"und null bedeutet. JSON Schema ist die reifste Konfigurationsvalidierungsmöglichkeit der drei – VS Code verwendet es, um tsconfig.json und package.json in der Editor-Übersicht zu validieren, mit inline-Fehlerhervorhebung. Wenn Werkzeuge deine JSON schreiben (webpack, tsc, npm), darfst du dich nicht um Lesbarkeit kümmern – das ist das, was der JSON-Formatierer dafür ist.

Fazit: Wähle je nach Kontext, nicht nach Vorliebe

Verwende JSON wenn Werkzeuge es generieren oder verarbeiten (package.json, tsconfig, AWS-Konfigurationen, GitHub-API-Antworten), oder wenn du JSON-Schema-Validierung brauchst. Vermeide nicht notwendig manuell geschriebene JSON. Die fehlende Kommentarfunktion schadet, aber die Allgemeinheit und die Werkzeugsupport sind schwer zu verlieren.

Verwende YAML wenn die Konfiguration hauptsächlich von Menschen erstellt wird und relativ flach ist – GitHub Actions-Workflows, Docker Compose-Dateien, Kubernetes-Manifeste. Zitier alles, was falsch als Boolean oder Zahl interpretiert werden könnte (Versionstrings, Landcodes, alles, das mit einer Ziffer beginnt). Führe einen Linter aus. Verwende nie Tabs. Behandle Typeninferenz als Bug, nicht als Feature.

Verwende TOML wenn du die Formatwahl kontrollierst und keine überraschenden Typumwandlungen willst. Es ist das ehrlichste der drei über das, was es ist. Wenn du ein Greenfield-Projekt startest und keines deiner Werkzeuge ein Format vorschreibt, ist TOML das unwahrscheinlichste, dass dich sechs Monate später überrasst. Die Unbekanntschaft ist eine einmalige Kosten; die Klarheit ist dauerhaft.

Das könnte Ihnen auch gefallen