TOML naar JSON omzetten

TOML is al jaren de standaard voor Python- en Rust-packaging, en de tooling rond een repository heeft dat niet altijd bijgehouden. Een CI-stap met alleen jq beschikbaar, een Node-script dat de versie uit een Cargo.toml moet lezen, een dashboard dat afhankelijkheden telt over tweehonderd repositories — ze kunnen allemaal JSON lezen en geen van alle TOML zonder een nieuwe afhankelijkheid.

Dat is het geval waar deze omzetting voor werkt, en het werkt schoon omdat de twee datamodellen bijna volledig overlappen. TOML is een tabel van sleutel-waardeparen met nesting en arrays, wat een JSON-object met nesting en arrays is.

Een kop tussen haakjes wordt een genest object, en een gepunte kop wordt meerdere niveaus diep genest — een kop geschreven voor een tool en daaronder een linter levert een object binnen een object op, zodat het JSON-pad de kop exact volgt.

Een kop tussen dubbele haakjes is de array van tabellen, en die wordt een JSON-array van objecten met één item per voorkomen. Daar staan de auteurs van een Python-pakket, de binaries van een Rust-crate en de doelen van een build in, en het is de constructie waar mensen het meest over piekeren en het minst hoeven te piekeren.

TOML is het enige formaat in deze familie met echte tijdstypen: offset-datetimes, lokale datetimes, lokale datums en lokale tijden staan in de specificatie, en een parser geeft ze terug als datums. JSON heeft geen datumtype, dus elk wordt een string.

De waarden overleven met één addertje. Een offset-datetime behoudt zijn offset in plaats van te worden genormaliseerd naar UTC. Een lokale tijd krijgt een millisecondencomponent die hij niet had — een tijd geschreven als acht uur ’s ochtends komt terug met een fractioneel deel eraan vast.

TOML 1.0 vereist dat een implementatie 64-bit gehele getallen aankan. JSON-getallen zijn IEEE-doubles en zijn alleen exact tot ongeveer negen biljard. Een TOML-bestand met een geheel getal boven dat bereik is volkomen legaal, en de parser hier stopt met een foutmelding dat het getal niet verliesvrij kan worden weergegeven, in plaats van JSON te produceren met een verkeerd getal erin.

Weigeren is de juiste keuze. Een stilzwijgend afgerond identificatienummer is een fout die weken later opduikt in een koppeling die niets matcht. Bevat je TOML zo’n waarde, quote die dan als string in de bron.

TOML-floats bevatten inf en nan als letterlijke waarden. JSON heeft geen van beide, en de serialiseerder schrijft null voor allebei. Dat is standaard JavaScript-gedrag en het is verliesgevend op een manier die nergens wordt gemeld — een geconfigureerde bovengrens van oneindig en een niet-ingestelde bovengrens worden hetzelfde in de JSON.

Het subtielere verlies is de typering. TOML onderscheidt een geheel getal van een drijvende komma, dus 1 en 1.0 zijn verschillende waarden met verschillende types, en een schema kan daarop vertrouwen. JSON heeft één getaltype, en 1.0 wordt geserialiseerd als 1.

Tabellen en sleutels komen eruit in de volgorde waarin de TOML ze declareerde, wat een geconverteerd bestand leesbaar houdt en een diff tussen twee omzettingen betekenisvol maakt. De uitvoer heeft een inspringing van twee spaties en eindigt met een nieuwe regel.

De uitzondering zijn numerieke sleutels. Een gequote TOML-sleutel die een getal is — voorkomend in configuraties die dingen indexeren op jaar of poort — wordt vooraan zijn object herschikt en oplopend gesorteerd, omdat JavaScript-objecten geheeltalige sleutels zo ordenen.

De uitvoer is gewone JSON, dus jq leest hem zonder vlaggen: een projectversie ophalen, afhankelijkheidsnamen tonen of controleren of een tool-sectie bestaat zijn allemaal eenregelige expressies.

Het opent ook validatie. JSON Schema is volwassen en breed geïmplementeerd, en TOML heeft geen schemataal in zijn specificatie, dus converteren en dan valideren is een echte manier om huisregels af te dwingen over veel repositories — elk pakket moet een licentie hebben, elke crate moet zijn editie vastpinnen.

TOML ondersteunt opmerkingen en gebruikt ze veelvuldig: de reden waarom een afhankelijkheid vastgezet is, het ticketnummer naast een workaround, het blok dat uitlegt bij welke omgeving een instelling hoort. JSON heeft onder RFC 8259 geen opmerkingsyntaxis, dus niets daarvan komt aan.

Dat bepaalt de richting van de relatie. De TOML is het bestand dat mensen bewerken en beoordelen, en de JSON wordt gegenereerd wanneer iets het moet lezen. De JSON naast de TOML in de repository zetten creëert twee versies van de waarheid die uit elkaar zullen groeien.

Gebeurt het lezen binnen een applicatie in plaats van een buildstap, gebruik dan een parser. Elke grote taal heeft er een — Python heeft al enkele versies tomllib in de standaardbibliotheek, en Rust, Go en JavaScript hebben goed onderhouden opties.

De converter verdient zijn plek aan de rand: een eenmalige inspectie, een CI-stap waar een afhankelijkheid toevoegen meer moeite is dan het waard, of een pijplijn waarvan de volgende fase alleen JSON spreekt. Alles draait in je browser, dus een privéconfiguratie met inloggegevens erin is hier veilig neer te zetten.