TOML vs. YAML (und JSON): Dieselbe Config auf drei Arten | We.Inc
Vergleiche TOML, YAML und JSON an denselben Config-Dateien direkt nebeneinander. Sieh, wo welches Format Pflicht ist, von pyproject.toml und Cargo.toml bis compose.yaml.
TOML ist ein INI-ähnliches Format für Config-Dateien: explizite [table]-Header, Strings in Anführungszeichen, echte Datumstypen und keine bedeutungstragende Einrückung. YAML setzt auf Einrückung, errät Typen aus nackten Werten und bietet zusätzlich Anker und mehrere Dokumente. Bei flachen Einstellungen ist TOML schwerer kaputtzumachen; bei tiefer Verschachtelung liest sich YAML besser.
TOML, YAML und JSON auf einen Blick
TOML 1.0
YAML 1.2
JSON
Verschachtelung
[table]- und [a.b]-Header
Einrückung
Geschweifte Klammern
Kommentare
Keine
Strings
Immer in Anführungszeichen
Anführungszeichen optional
Immer in doppelten Anführungszeichen
Datum und Uhrzeit
Eingebaute Typen
Nicht im Core Schema von 1.2
Nur als Strings
Groß- und Kleinschreibung beachtet
Ja
Ja
Ja
Medientyp
application/toml
application/yaml
application/json
Meistens hast du keine Wahl: Python-Packaging liest pyproject.toml, Rust liest Cargo.toml, und GitHub Actions sowie Docker Compose lesen YAML. Wenn du doch wählen kannst, macht eine Config in allen drei Formaten die Abwägungen offensichtlich. Wähle unten ein Beispiel und vergleiche.
Wähle eine der Beispiel-Configs: App-Einstellungen, ein Paketmanifest oder eine Serverliste.
Lies dieselben Daten in TOML, YAML und JSON nebeneinander.
Achte darauf, wo TOML Header braucht ([[servers]]) und wo YAML sorgfältige Einrückung verlangt.
Kopiere die Version, die dein Tool erwartet.
Bei langen Listen ähnlicher Einträge wird TOML wortreich: Jeder Eintrag braucht seinen eigenen [[name]]-Header.
TOML verbietet, denselben Schlüssel oder dieselbe Tabelle zweimal zu definieren. Das fängt Copy-and-paste-Fehler ab, die YAML je nach Parser durchlassen kann.
Setze Versionsnummern in YAML in Anführungszeichen. TOML hat diese Falle nicht, weil nackter Text dort nie ein gültiger String ist.
Bleib nach Möglichkeit bei einem Format pro Repository. Gemischte Formate sind nur dann in Ordnung, wenn jedes Tool sein eigenes verlangt.
Häufige Fragen
Ist TOML besser als YAML?
Keines gewinnt überall. Die expliziten Header und Pflicht-Anführungszeichen von TOML machen kleine und mittlere Config-Dateien schwer misszuverstehen. YAML bewältigt tiefe Verschachtelung und lange Listen mit weniger Ballast, zum Preis einer leerzeichenempfindlichen Syntax und impliziter Typisierung.
Warum nutzt Python pyproject.toml?
Die Python-Packaging-Leitfäden definieren pyproject.toml mit drei Tabellen: [build-system] für das Build-Backend, [project] für Metadaten wie Name, Version und Abhängigkeiten und [tool] für Einstellungen einzelner Tools wie Linter.
Kann TOML alles darstellen, was YAML kann?
Nicht alles. TOML hat keine Anker oder Aliase, keine mehreren Dokumente pro Datei und kein null, da jeder Schlüssel einen Wert bekommen muss. Für Konfiguration spielt das selten eine Rolle, aber YAML-Daten, die auf diese Funktionen setzen, lassen sich nicht eins zu eins umwandeln.
Welche Formate akzeptieren Docker Compose und GitHub Actions?
Beide nutzen YAML. Workflows für GitHub Actions liegen in .github/workflows mit der Endung .yml oder .yaml, und Compose sucht standardmäßig nach compose.yaml, akzeptiert für ältere Projekte aber weiterhin docker-compose.yaml.
Unterstützt TOML mehrzeilige Strings?
Ja. Drei doppelte Anführungszeichen beginnen einen mehrzeiligen Basic String, der Escapes erlaubt, und drei einfache Anführungszeichen beginnen einen mehrzeiligen Literal String, der seinen Inhalt genau so behält, wie er geschrieben ist.
Wo welches Format Pflicht ist
Python-Projekte beschreiben sich in pyproject.toml und Rust-Crates in Cargo.toml, daher ist TOML in diesen Ökosystemen die Norm. Hugo akzeptiert außerdem TOML-Front-Matter zwischen +++-Zeilen.
CI-Pipelines, Container-Setups und Deployment-Manifeste setzen auf YAML: Workflows für GitHub Actions und Docker-Compose-Dateien sind beide YAML, und die gewählte Dateiendung ist vor allem eine Frage der Einheitlichkeit.
Was TOML für Sicherheit aufgibt
Das Ziel von TOML ist laut eigener Spezifikation, eindeutig auf eine Hashtabelle abzubilden. Das heißt: kein Raten. Text braucht Anführungszeichen, Booleans sind nur true und false, und jede Tabelle wird in einem Header benannt.
Der Preis ist Wiederholung bei verschachtelten Daten. Drei Ebenen tief wiederholt eine TOML-Datei den Tabellenpfad in jedem Header, während YAML einfach einrückt.
Welche Dateien welches Format nutzen
Gängige Config-Dateien und das Format, das sie verlangen
Datei
Format
Gelesen von
TOML
Python-Build-Tools und Packaging
Cargo.toml
TOML
Cargo, dem Rust-Paketmanager
.github/workflows/*.yml
YAML
GitHub Actions
YAML
Docker Compose
JSON
npm und anderen Node-Paketmanagern
Markdown-Front-Matter
YAML (TOML mit +++ in Hugo)
Static Site Generators
Wissenswerte TOML-Syntax
Dotted Keys, Inline-Tabellen und Datumswerte
Dotted Keys und Inline-Tabellen ersparen zusätzliche Header für kleine Gruppen, und Datumswerte sind typisierte Werte, keine Strings.
Eine Config in TOML, YAML und JSON
Wähle ein Beispiel. Alle drei Versionen enthalten genau dieselben Daten, sodass du vergleichen kannst, wie jedes Format sie ausschreibt.
Beispiel-Config
TOML
YAML
JSON
Im Beispiel mit App-Einstellungen speichert TOML opens als echte lokale Uhrzeit, während die YAML- und JSON-Versionen es als String behalten.