TOML naar XML omzetten

De interessante versie van deze omzetting is geen configuratiemigratie. Het is een rapportage- of indieningsstap: de feiten over een project staan in een TOML-manifest omdat Cargo, pip en Hugo daarvoor kozen, en het systeem dat die feiten wil — een licentieregister, een leveranciersportaal, een interne compliance-importer — leest al sinds 2004 XML.

Je zoekt dus geen getrouwe weergave van TOML in XML, want niemand aan de andere kant geeft om TOML. Je zoekt hoe dicht de uitvoer bij een documentvorm komt die iemand anders heeft gedefinieerd, en welke hiaten je zelf moet dichten.

XML heeft precies één hoofdelement nodig, en een TOML-document is een tabel met willekeurig veel sleutels, dus wordt een regel toegepast. Heeft het bestand precies één sleutel op het hoogste niveau en bevat die een tabel, dan wordt die sleutel het hoofdelement — een bestand met alleen een [tool]-sectie levert een <tool>-document op. Zijn er meerdere sleutels op het hoogste niveau, dan wordt alles verpakt in een generiek <root>.

Dat hernoemen is bijna altijd de eerste bewerking. Wordt de omzetting herhaald, dan is het netter om de TOML zelf te herstructureren: nest het hele manifest onder één tabel met de naam die het schema wil.

Een [[bin]]-blok dat driemaal herhaald wordt, is TOML’s manier om een lijst records te schrijven, en dat wordt drie naast elkaar staande <bin>-elementen, elk met eigen kinderen — precies hoe XML een lijst weergeeft, zonder wrapper-element.

Een gewone array van losse waarden gedraagt zich hetzelfde: tags = ["a", "b"] wordt twee <tags>-elementen met tekstinhoud in plaats van één element met een kommagescheiden string.

TOML heeft ongewoon genoeg vier temporele typen in plaats van één, en de omzetting houdt ze uit elkaar in plaats van ze samen te voegen tot één UTC-tijdstip. Een offset-datumtijd en een lokale datumtijd worden allebei geldige xs:dateTime; een lokale datum wordt xs:date; een lokale tijd wordt xs:time.

Elke waarde krijgt er wel een millisecondencomponent bij die de manifest niet had — 08:00:00 wordt 08:00:00.000. Alle drie XSD-typen accepteren fracties van seconden, dus validatie blijft in orde, maar een vergelijking tegen een letterlijk geschreven kortere waarde matcht niet meer.

De offset wordt precies zoals geschreven overgenomen in plaats van genormaliseerd: 2026-03-01T08:00:00+02:00 komt aan als 2026-03-01T08:00:00.000+02:00, niet als 06:00:00.000Z. Dat is de betere keuze voor een document dat iemand leest.

Een lokale tijd zonder datum — at = 08:00:00 — heeft geen datum, dus een element dat het schema als xs:dateTime declareert, weigert de waarde. Declareer dat element dan als xs:time, of voeg de datum toe in de TOML waar hij thuishoort.

TOML staat bijna elke sleutel toe als hij tussen aanhalingstekens staat: "2024 report", "line-length", "x:y". XML-elementnamen mogen niet met een cijfer beginnen en geen spatie of, zonder gedeclareerde namespace, een dubbele punt bevatten.

De schrijver herschrijft in plaats van te weigeren: alles buiten letters, cijfers, underscore, streepje en punt wordt een underscore. Zo wordt "2024 report" <_2024_report> en "x:y" <x_y> — die laatste is de belangrijkste om op te letten.

Standaard wordt elke TOML-sleutel een kind-element. De conventie voor attributen is een apenstaartje vóór de sleutelnaam: binnen een tabel geeft "@id" = 42 id="42" op dat element in plaats van een <id>-kind.

Teksteninhoud naast attributen gebruikt de sleutel "#text" op dezelfde manier. Beide zijn de moeite waard, want ze maken van een tweeledige klus één stap.

Er wordt geen XML-declaratie geschreven, dus het document begint bij het hoofdelement. Er wordt geen namespace gedeclareerd en geen schemalocatie verwezen. De uitvoer springt twee spaties per niveau in.

Een lege TOML-array is een ander stil geval: tags = [] levert geen element op, alleen een lege regel. Dat is verdedigbaar, maar verrast een schema dat het element met minOccurs="1" declareert.

Beide formaten ondersteunen commentaar, en geen van beide kanten neemt het over, dus elke #-regel die uitlegt waarom een afhankelijkheid vastgezet is, ontbreekt in de XML.

Behandel de XML als een gegenereerd artefact, niet als een kopie. Regenereer het telkens wanneer het manifest wijzigt, en houd het buiten de repository tenzij het indieningsproces een gecommit exemplaar vereist.

Alles hierboven is een reden waarom de eerste poging niet zal valideren: het hoofdelement heeft de verkeerde naam, een lokale tijd voldoet niet aan een element gedeclareerd als xs:dateTime, sommige waarden zijn kind-elementen waar het schema attributen wil.

xmllint --schema contract.xsd out.xml --noout geeft de volledige lijst met klachten en regelnummers. Werk die door met aanpassingen aan de TOML in plaats van aan de XML, zodat de volgende run vanaf een betere plek begint.