NDJSON naar TOML omzetten

Mensen nemen aan dat TOML niet kan wat JSON kan, en voor een lijst records klopt dat niet. Een array van tabellen wordt geschreven als dezelfde kop herhaald tussen dubbele haken — [[items]] drie keer geeft drie records — met elk blok zijn eigen sleutels eronder. Het is de constructie die Cargo gebruikt voor afhankelijkheden en Hugo voor menu-items.

Vergeleken met de JSON waar het uit komt is het uitgebreider en aanzienlijk makkelijker te bewerken. Een record toevoegen betekent vier regels kopiëren in plaats van haakjes balanceren en een komma onthouden, en een diff van een wijziging aan één record raakt alleen dat blok. Voor een bestand dat een mens onderhoudt is dat het hele argument.

Een TOML-document moet bovenaan een tabel zijn, en een regelgescheiden bestand is een lijst zonder eigen naam. De lijst krijgt dus een plaatshoudernaam: de uitvoer is een reeks [[items]]-blokken, één per regel van de bron.

Die naam is het eerste om te veranderen, en het is zoeken-en-vervangen over de blokkoppen — naar [[dependencies]], [[authors]], [[products]], wat het gereedschap dat het bestand leest ook verwacht. Niets in een NDJSON-bestand kan de converter vertellen wat de records zijn, dus is de plaatshouder met opzet en met opzet duidelijk, in plaats van een gok die plausibel zou kunnen ogen en fout is.

Dit is het stille voordeel van TOML boven elk tabulair doel voor hetzelfde bestand. Een CSV, een Parquet-bestand of een reeks INSERT-statements moet records verzoenen tot één set kolommen, met blanco's waar een record niets had. Een array van tabellen hoeft dat niet: elk blok draagt precies de sleutels die zijn regel had.

Een bestand waar latere records een veld erbij kregen zet dus om zonder nulls, zonder lege cellen en zonder verbreding. Het resultaat leest als wat het is — een lijst records die grotendeels op elkaar lijken — in plaats van als een schaars rooster. Voor een fixtureset die in de loop van de tijd is opgebouwd is dat meestal de eerlijkere weergave.

TOML kent geen null-letterlijk, en de schrijver verzint er geen. Een sleutel wiens JSON-waarde null was wordt simpelweg niet in het blok geschreven, op het hoogste niveau van een record of waar dan ook binnenin.

Of dat uitmaakt is een vraag over het gereedschap dat het bestand leest. Veel gereedschappen behandelen een ontbrekende sleutel en een lege waarde identiek en vallen bij beide terug op een standaard, en daarvoor is niets verloren. Waar het onderscheid gedrag stuurt, heeft de omzetting de data stilletjes veranderd, en de goedkoopste verdediging is de bron doorzoeken op null vóór het omzetten in plaats van de twee bestanden achteraf te vergelijken — een ontbrekende regel is veel lastiger te zien dan een veranderde.

Een record met een genest object levert een subtabel op onder zijn blok: een author-object in een record wordt een [items.author]-kop met zijn sleutels eronder. Diepte wordt uitgedrukt in de kop in plaats van in inspringing, dus zelfs drie niveaus blijven plat op de pagina.

Het is op elke diepte geldig en onprettig na twee of drie niveaus. Een kop als [items.metadata.source.system] is geldig en niemand geniet ervan die te lezen, en een fixturebestand dat die oplevert draagt meestal meer structuur dan een handmatig bewerkt bestand hoort te dragen. Dat is een signaal over de data, niet over de omzetting.

Een TOML-tabelkop claimt elke regel die erna geschreven wordt tot de volgende kop, dus een losse sleutel onder een blok zou stilletjes onderdeel van dat blok worden. De schrijver zet dus elke losse waarde op het hoogste niveau boven het eerste kopje.

Voor dit paar komt dat zelden voor, want de invoer is een lijst en alles komt in een blok terecht. Het telt wanneer je het bestand achteraf bewerkt: een version-sleutel onderaan het bestand toevoegen zet hem binnen het laatste record in plaats van op het hoogste niveau, wat de meest gemaakte fout met TOML is. Voeg zulke sleutels bovenaan toe, boven de eerste dubbele-hakenkop.

TOML 1.0 heeft vier datum- en tijdtypen, waaronder een offset-datumtijd die een echte waarde is en geen tekst. JSON heeft er geen — elke tijdstempel in elk JSON-bestand is naar afspraak een tekenreeks of een getal — dus een waarde als "2024-01-01T00:00:00Z" wordt geschreven als een geciteerde TOML-tekenreeks.

Dat is correct en het is niet wat het formaat zou kunnen uitdrukken. Wil het gereedschap dat het bestand leest een echte datumtijd, dan is de aanhalingstekens weghalen op die regels de hele oplossing, en verder hoeft er niets aan het bestand te veranderen. Een redelijk ding om te doen terwijl je toch bezig bent de blokkoppen te hernoemen.

Een paar dozijn is comfortabel. Een paar honderd is een bestand dat niemand leest maar een gereedschap nog snel verwerkt. Een paar duizend blokken is een configuratiebestand in naam alleen, en op dat punt houdt elke eigenschap die TOML aantrekkelijk maakte — leesbare diffs, handmatig bewerken, commentaar naast waarden — op te gelden.

De stopregel is de moeite waard om eerlijk toe te passen: als niemand het bestand gaat openen, zet het dan niet om naar een configuratieformaat. CSV is kleiner en elk gereedschap leest het, JSON is wat de data al was, en een database is wat je wilt als de lijst herhaaldelijk bevraagd gaat worden. TOML verdient zijn plek alleen wanneer een mens het resultaat gaat onderhouden.

Commentaar, wat de hele reden is waarom configuratieformaten er zo uitzien. JSON heeft er geen, en een regelgescheiden bestand ervan gemaakt ook niet, dus wonen de redenen achter de waarden in een fixtureset momenteel in een commitboodschap of nergens.

Zodra het bestand TOML is, kunnen die redenen naast de items staan: waarom dit record buiten een test valt, welke identifier stroomopwaarts een waarde moet matchen, wat breekt als een item wordt herschikt. Dat is informatie die een gegenereerd bestand nooit kon dragen, en de eerste minuten na de omzetting zijn het goedkoopste moment om het op te schrijven.

Beide helften zijn JavaScript in dit tabblad: het bestand wordt regel voor regel gelezen en de TOML wordt geschreven door een kleine bibliotheek die op verzoek wordt geladen. Er wordt niets geüpload, er is geen account, en de gratis laag accepteert tot 100 MB — voor een bestand waarvoor deze omzetting geschikt is, is dat geen grens die iemand nadert.

Het privacypunt blijft ook op deze schaal gelden. Een fixtureset is vaak echte data met de namen erin gelaten, en een seed-bestand voor een ontwikkeldatabase is regelmatig een deel van productie. Het niet ergens heen sturen is hier een kleinere beslissing dan bij een logbestand, en het blijft de juiste standaard.