TOML naar YAML omzetten

De feiten over een project staan steeds vaker in een TOML-bestand — de pakketnaam, de ondersteunde Python- of Rust-versies, de featurevlaggen, de dependencylijst. Wat die feiten verbruikt is, met dezelfde consistentie, YAML: een GitHub Actions-workflow, een Helm-waardenbestand, een Ansible-variabelenset. Niemand koos deze splitsing bewust.

De taak is dus meestal geen migratie maar een overschrijving: krijg de waarden accuraat in YAML-syntax, en verplaats dan de delen die je nodig hebt naar een bestand met een eigen vorm. Dat onderscheid is het onthouden waard, want het verandert wat "juiste uitvoer" betekent.

TOML is ongewoon onder configuratieformaten door echte datum- en datumtijdtypen te hebben, geschreven zonder aanhalingstekens: launch = 2026-03-01T08:00:00Z. Ze komen op dezelfde manier in de YAML terecht — launch: 2026-03-01T08:00:00.000Z — zonder aanhalingstekens eromheen, wat YAML reserveert voor een tijdstempel.

Wat dat oplevert hangt volledig af van de loader. Lees de uitvoer terug met dezelfde bibliotheek die haar schreef, die de YAML 1.2 core-schema volgt, en elke waarde komt terug als string: 1.2 heeft geen tijdstempel-resolver. Lees het met PyYAML of Ruby’s Psych, beide nog op YAML 1.1, en ze worden datumtijden — maar een kaal lokaal tijdstip zoals 08:00:00.000 komt terug als het getal 28800.

Beide doelen schrijven dezelfde tekens voor een datum, dus het argument gaat over waar het type woont. In de YAML is de waarde zonder aanhalingstekens en zelfbeschrijvend genoeg dat een 1.1-loader haar zal typeren zonder dat het gezegd wordt. In XML is dezelfde datum elementtekst, en wat ze betekent komt van een schema dat iemand anders onderhoudt.

Dat werkt beide kanten op. Kies YAML als de bestemming een workflow of waardenbestand is dat de waarde met zijn eigen loader teruglezen zal en jij weet welke loader dat is; kies XML als iets stroomafwaarts het document gaat valideren en je liever dan van het probleem hoort.

Een [package]-kop wordt een top-level sleutel met zijn waarden twee spaties eronder ingesprongen. Een [tool.black]-kop wordt tool: met daarin black: met daarin de instellingen, want een gestippelde tabelkop is nesting en geen naam met puntjes erin.

De volgorde is de volgorde waarin de parser ze zag. Wat wel verschuift is alles uitgedrukt met gestippelde sleutels verspreid door het bestand — die worden verzameld onder één ouder in de YAML, wat leesbaarder is en niet hoe de brontekst eruitzag.

Dit is de echte overgang en makkelijk te missen omdat de uitvoer er zo op elkaar lijkt. In TOML is enabled = true een boolean omdat de syntax het zegt, en version = "1.0" is een string omdat het tussen aanhalingstekens staat. In YAML is een scalair zonder aanhalingstekens wat de parser besluit dat het is.

De schrijver quote defensief waar het telt: een reeks cijfers komt gequote uit, dus version: "1.0" blijft version: "1.0" en niet het getal 1. Wat niet gequote wordt zijn NO, yes, on en off, want onder YAML 1.2 zijn dat gewone strings — laad ze met PyYAML of Psych en ze worden booleans.

Een herhaald [[bin]]- of [[tool.poetry.packages]]-blok is TOML’s lijst-van-records-vorm, en het zet om naar de vorm die iedereen met de hand schrijft in YAML: een streepje per item, sleutels eronder ingesprongen. Gewone arrays gedragen zich hetzelfde.

Dat blokformaat is wat de meeste YAML-tools documenteren, dus items plakken meestal zonder herformattering in een workflow of waardenbestand. Wil de bestemming echt flow-stijl — een matrixregel geschreven als [3.11, 3.12, 3.13] — dan is dat een kleine handmatige bewerking.

Een TOML-string tussen drievoudige aanhalingstekens met een script of een licentiefragment behoudt zijn regelstructuur. De schrijver produceert een blokscalair — de sleutel, dan een verticale streep, dan de echte regels eronder ingesprongen — in plaats van één regel met ontsnappingstekens.

Lange enkelregelige waarden worden anders behandeld: een string zonder regeleinden maar met veel lengte wordt gevouwen op vervolgregels rond de tachtig kolommen, en YAML leest die vouwen terug als spaties, dus de waarde blijft ongewijzigd.

TOML en YAML ondersteunen allebei #-commentaar, en een manifest zit er vaak vol mee: waarom een dependency vastgepind is, welke van twee instellingen bewust is. Niets daarvan overleeft, want de lezer negeert commentaar bij het inlezen en de schrijver heeft er geen om te plaatsen.

Voor een fragment dat je zo gaat plakken is dat onopvallend. Voor iets dat je bewaart, is het de reden dat de TOML de bron van waarheid blijft en de YAML gegenereerd wordt: twee bestanden met dezelfde waarden en maar één met de redenering.

De goedkoopste controle is een rondje. Laad de uitvoer met wat haar uiteindelijk zal laden en vergelijk een handvol waarden met het manifest — de versie, een datum, alles dat op een getal leek en eigenlijk een string moet zijn.

Doe het eenmaal en het is sneller dan een pijplijn debuggen die draaide met version: 1 waar je "1.0" bedoelde.

In dit browsertabblad, door gewone JavaScript. Niets wordt geüpload, er is geen engine op te halen, geen account en geen daglimiet — het netwerktabblad openen en iets omzetten bevestigt het.

Manifesten zijn klein genoeg dat de grens van 100 MB theoretisch is, maar ze zijn niet altijd openbaar. De dependencylijst van een privérepository noemt interne pakketten en interne registries, en een [tool]-blok verraadt soms meer over een organisatie dan bedoeld.