Was ist eine TOML-Datei?

TOML ist ein reines Textformat, das sich in jedem Editor öffnen lässt. Eingesetzt wird es für die Bearbeitung.

Die Endung lautet .toml, der volle Name Tom's Obvious Minimal Language. Beides sagt weniger aus als das, was die Datei halten kann — und davon handelt der Rest dieser Seite.

Es geht auf 2013 zurück. Die Spezifikation ist TOML 1.0.

Das Alter ist aus einem praktischen Grund interessant: je älter ein Format, desto mehr Programme hatten Zeit, es zu lernen.

Sie ist vollständig veröffentlicht, das Format lässt sich also aus dem Dokument umsetzen statt durch Nachsehen. Deshalb taucht es in so vielen Programmen auf, und deshalb gehen Dateien von vor zwanzig Jahren heute noch auf. Veröffentlicht heißt allerdings nicht lizenzfrei: Wo ein Format einen Codec einpackt, ist die Patentfrage eine eigene, die der Standard nicht mitbeantwortet.

TOML speichert seinen Inhalt exakt. Erneutes Speichern ändert nichts, es lässt sich also beliebig oft öffnen, bearbeiten und wieder ablegen, ohne dass sich Schaden ansammelt — genau das macht es zu einem Arbeitsformat und nicht zu einem Ausgabeformat.

TOML hat eine Kommentarsyntax — das ist der Unterschied zwischen einer Datei, die ein Mensch pflegt, und einer, die ein Programm schreibt. Beim Umwandeln in ein Format ohne Kommentare sind sie das Erste, was verschwindet, und gewarnt wird nicht.

Visual Studio Code liest es, und die meisten Programme derselben Art ebenfalls.

Wenn eine Datei nicht aufgeht, liegt es selten am Format — häufiger daran, dass das Programm älter ist als das Format. Die Umwandlung in etwas Älteres ist der verlässliche Weg daran vorbei, und dafür gibt es den Rest dieser Website.

Kein Browser liest es.

Das ist der häufigste Grund, es umzuwandeln: nicht dass das Format schlecht wäre, sondern dass die Stelle, an der die Datei erscheinen soll, es nicht lesen kann.

TOML ist zum Öffnen und Ändern gedacht. Behalte die Datei in diesem Format, solange die Arbeit läuft, und exportiere daraus, wann immer eine fertige Fassung gebraucht wird.

In TOML steht 30 für eine Ganzzahl, 30.0 für eine Gleitkommazahl, true für einen Wahrheitswert, "30" für eine Zeichenkette und 2026-08-05 für ein Datum — jeder Parser liest denselben Wert auf dieselbe Art, weil das Format selbst festlegt, was dasteht, statt es zu erraten.

Genau darum geht es bei TOML. Die typischen Konfigurationsfehler entstehen an dieser Stelle: ein Schalter, der als Zeichenkette "false" gelesen und für wahr gehalten wird, eine Versionsnummer, die zur Gleitkommazahl wird, ein Port, der plötzlich Text ist. Ein Format mit festen Typen macht diese ganze Fehlerklasse unmöglich.

YAML kann mehr und lässt sich leichter falsch schreiben, und TOML wurde als direkte Antwort darauf entworfen. In YAML entsteht Struktur durch Einrückung — eine verrutschte Leerstelle ändert die Bedeutung einer Datei, ohne dass ein Fehler gemeldet wird, denn die Datei bleibt gültig, nur eben mit anderem Inhalt.

Dazu kommt die stille Typerkennung älterer YAML-Parser: no wird zum Wahrheitswert false, aus einer Versionsnummer wie 1.20 wird die Zahl 1.2, ein zeitartiger Text wird zur Sechzigersystem-Zahl. Jeder dieser Fälle hat schon echte Ausfälle verursacht. In TOML gibt es davon keinen: Struktur ist immer sichtbar geschrieben, und ein Wert ist genau das, was seine Schreibweise sagt.

Rust hat es von Anfang an überall benutzt — jedes Cargo-Projekt hat eine Cargo.toml —, und Python ist gefolgt: pyproject.toml ist inzwischen der Standardort für die Build-Konfiguration, und die Standardbibliothek liest TOML ohne zusätzliches Paket.

Daneben Hugo und mehrere Generatoren für statische Websites, Netlify, Poetry, Ruff und eine ganze Reihe neuerer Werkzeuge, die eine von Hand editierbare Konfiguration ohne das Einrückungsrisiko wollten. TOML ist damit ungefähr das geworden, was YAML für Infrastrukturcode ist — nur eben für Konfiguration, die Entwickler direkt anfassen.

Eine Überschrift in eckigen Klammern ist eine Tabelle, TOMLs Wort für einen Abschnitt. Verschachtelung geschieht über einen Punkt: [tool.ruff.lint] beschreibt eine Tabelle in einer Tabelle in einer Tabelle, und die Punkte sind Struktur, kein Teil eines Namens — genau an dieser Stelle hört INI auf und TOML fängt an.

Doppelte Klammern sind der Teil, der jedem irgendwann Kopfzerbrechen bereitet. [[bin]] dreimal wiederholt definiert nicht dreimal dieselbe Tabelle neu, sondern ein Array von Tabellen: drei Einträge in einer Liste. So drückt man "mehrere Dinge derselben Art" aus — drei Programme, vier Abhängigkeiten, eine Liste von Autoren —, und wenn eine Konfiguration sich still selbst überschreibt statt sich anzusammeln, sind einfache Klammern anstelle doppelter fast immer der Grund.

TOML gehört zu den Formaten, deren Baumstruktur beim Konvertieren erhalten bleibt: Verschachtelung wird nicht wie bei CSV oder Parquet in Punktnotation flachgeklopft, sondern bleibt Struktur, genau wie bei JSON, YAML und XML. Ein tief verschachteltes Objekt kommt also als solches an, nicht als eine Reihe von Spalten mit Punkten im Namen.

Was dabei verloren geht, sind Kommentare — jeder Kommentar in einer TOML-Datei fällt beim Parsen weg, und kein Format, in das oder aus dem konvertiert wird, hat dafür einen Platz. Die Reihenfolge der Schlüssel bleibt dagegen erhalten, weil an keiner Stelle sortiert wird. Wer eine handgepflegte TOML-Datei mit sorgfältig platzierten Erklärungen durch den Konverter schickt, bekommt die Werte zurück und die Erklärungen nicht.

TOML kennt Datum und Uhrzeit als eigenen Typ: ein Datum für sich, eine Uhrzeit für sich, ein Zeitstempel mit oder ohne Zeitzonenangabe. Sie sind Werte wie Ganzzahlen, keine Zeichenketten, die irgendein Programm hinterher noch interpretieren muss.

Das ist ein kleines Feature, das eine dauerhafte Quelle für Ärger beseitigt. Eine Konfiguration mit Veröffentlichungsdatum, Ablaufdatum oder Zeitplan braucht kein vereinbartes Textformat mehr, das in einem Kommentar dokumentiert und von jedem Konsumenten neu implementiert wird. Das Format legt es fest, der Parser liefert ein Datum zurück.

Tief verschachtelte Daten. TOML ist auf Flachheit und Lesbarkeit ausgelegt, und sobald die Struktur drei oder vier Ebenen erreicht, werden die Tabellenüberschriften lang und die Datei unübersichtlicher als das JSON, das sie ersetzen sollte. Sieht die Konfiguration aus wie ein Dokumentbaum, will sie wahrscheinlich auch einer bleiben.

Der andere Fall ist maschinell erzeugter Datenaustausch. TOML ist für Dateien gedacht, die Menschen bearbeiten; JSON ist für Dateien, die Programme untereinander austauschen, und ist kleiner, schneller zu lesen und überall unterstützt. TOML dafür einzusetzen ist möglich und bringt nichts — die Lesbarkeit, für die es bezahlt, lohnt sich nur, wenn wirklich ein Mensch mitliest.