Wat is een TOML-bestand?

TOML is een puur tekstformaat dat in elke editor opengaat. Het wordt gebruikt voor bewerken.

De extensie is .toml en de volledige naam Tom's Obvious Minimal Language. Allebei zeggen ze minder dan wat het bestand kan bevatten, en daar gaat de rest van deze pagina over.

Het gaat terug tot 2013. De specificatie is TOML 1.0.

De leeftijd is om een praktische reden interessant: hoe ouder een formaat, hoe meer programma’s de tijd hebben gehad om het te leren.

Ze is volledig gepubliceerd, dus wie het formaat wil uitvoeren kan dat uit het document doen in plaats van door te kijken hoe anderen het doen. Daarom duikt het in zo veel programma’s op, en daarom gaan bestanden van twintig jaar geleden nog steeds open. Openbaar is niet hetzelfde als royaltyvrij: waar een formaat een codec omhult, is de octrooilicentie een aparte vraag waarop de standaard geen antwoord geeft.

TOML bewaart zijn inhoud precies. Opnieuw opslaan verandert niets, dus je kunt het zo vaak openen, bewerken en wegschrijven als je wilt zonder dat er schade opstapelt — en dat is wat er een werkformaat van maakt in plaats van een afleverformaat.

TOML heeft een commentaarsyntaxis — dat is het verschil tussen een bestand dat een mens onderhoudt en een bestand dat een programma schrijft. Bij het converteren naar een formaat zonder commentaar zijn ze het eerste wat verdwijnt, en er wordt niet gewaarschuwd.

Visual Studio Code leest het, en de meeste programma’s van dezelfde soort ook.

Als een bestand niet opengaat ligt het zelden aan het formaat — vaker is het programma ouder dan het formaat. Converteren naar iets ouders is de betrouwbare weg eromheen, en daarvoor is de rest van deze site bedoeld.

Geen enkele browser leest het.

Dat is veruit de meest voorkomende reden om het te converteren: niet dat het formaat slecht is, maar dat de plek waar je het bestand wilt tonen het niet kan lezen.

TOML is bedoeld om te openen en te wijzigen. Houd het bestand in dit formaat zolang het werk loopt, en exporteer eruit wanneer er een afgeronde versie nodig is.

TOML oogt als INI en gedraagt zich als een dataformaat. Een waarde geschreven als 30 is een geheel getal, 30.0 een kommagetal, true een boolean, "30" een tekenreeks, en 2026-08-05 een datum — het formaat definieert ze allemaal.

Die ene eigenschap is het grootste deel van de reden dat het bestaat. Configuratiebugs clusteren rond precies deze dubbelzinnigheid: een vlag gelezen als de tekenreeks "false" en als waar bevonden, een versienummer stilletjes een kommagetal geworden.

YAML kan meer en is veel makkelijker fout te doen, en TOML is geschreven als direct antwoord daarop. Structuur in YAML wordt uitgedrukt met inspringing, dus een verkeerd geplaatste spatie verandert de betekenis van een document zonder een foutmelding te geven.

Dan is er de type-inferentie. Oudere YAML leest no als een boolean, dus een landcode wordt false. Versienummers als 1.20 worden het kommagetal 1.2. TOML heeft niets van dit alles: structuur is expliciet, en een waarde is wat zijn syntax zegt.

Rust bracht het overal eerst — elk Cargo-project heeft een Cargo.toml — en Python volgde beslissend: pyproject.toml is nu de standaardplek voor buildconfiguratie.

Daarnaast Hugo en verschillende statische-sitegeneratoren, Netlify, Poetry, Ruff, en een gestage stroom nieuwere tools die configuratie wilden die een mens kon bewerken zonder het inspringingsrisico.

Een header tussen rechte haken is een tabel, TOML’s woord voor een sectie. Nesten gebeurt met een punt: [tool.ruff.lint] declareert een tabel in een tabel in een tabel.

Dubbele rechte haken zijn wat iedereen verrast. [[bin]] driemaal herhaald herdefinieert geen tabel driemaal; het declareert een array van tabellen, drie items in een lijst. Wordt configuratie stilletjes overschreven in plaats van opgeteld, dan is enkele haken waar dubbele hoorden vrijwel altijd de reden.

TOML begrijpt datums en tijden rechtstreeks: een losse datum, een losse tijd, en een tijdstempel met of zonder offset. Ze zijn waarden zoals gehele getallen dat zijn, geen tekenreeksen die iets achteraf moet parsen.

Dit is een kleine functie die een aanhoudende ergernis wegneemt. Configuratie met een releasedatum of vervaldatum hoeft niet langer een afgesproken tekenreeksformaat in commentaar te documenteren.

Diep geneste data. TOML is bedoeld om plat en leesbaar te zijn, en zodra structuur drie of vier niveaus diep gaat, worden de headernamen lang. Lijkt je configuratie op een documentboom, dan wil het er waarschijnlijk ook een zijn.

Machinaal gegenereerde data is het andere geval. TOML is voor bestanden die mensen bewerken; JSON is voor bestanden die programma’s uitwisselen, en is kleiner en sneller te parsen.

Elke teksteditor, en een met TOML-ondersteuning is de moeite waard voor iets substantieels — hij toont meteen een niet-afgesloten tekenreeks of een misvormde tabelheader.

Twee gewoontes voorkomen de meeste fouten. Houd elke sleutel binnen de tabelheader waar hij bij hoort. En zet geen aanhalingstekens om getallen of booleans — dat maakt ze tekenreeksen, en de instelling lijkt genegeerd te worden zonder zichtbare reden.