NDJSON in TOML umwandeln

Die verbreitete Annahme, TOML könne nicht abbilden, was JSON kann, stimmt bei einer Liste von Datensätzen nicht. Ein Array von Tabellen wird als derselbe Header in doppelten eckigen Klammern wiederholt geschrieben — dreimal [[items]] ergibt drei Datensätze —, wobei jeder Block seine eigenen Schlüssel darunter trägt. Genau dieses Konstrukt nutzt Cargo für Abhängigkeiten und Hugo für Menüeinträge.

Gegenüber dem JSON, aus dem es entstand, ist das ausführlicher und deutlich leichter zu bearbeiten. Einen Datensatz hinzuzufügen bedeutet vier Zeilen zu kopieren statt Klammern auszubalancieren und an ein Komma zu denken, und ein Diff einer Änderung an einem Datensatz betrifft nur diesen einen Block. Für eine Datei, die eine Person pflegt, ist das der ganze Vorteil.

Ein TOML-Dokument muss auf oberster Ebene eine Tabelle sein, eine zeilenweise Datei ist aber eine namenlose Liste. Die Liste bekommt deshalb einen Platzhalternamen: Die Ausgabe ist eine Folge von [[items]]-Blöcken, einer pro Zeile der Quelle.

Dieser Name ist als Erstes zu ändern — ein Suchen-und-Ersetzen über die Block-Header, etwa zu [[dependencies]], [[authors]], [[produkte]], je nachdem, was das lesende Werkzeug erwartet. Aus einer NDJSON-Datei selbst lässt sich nicht ableiten, wofür die Datensätze stehen, deshalb ist der Platzhalter bewusst offensichtlich statt eine Vermutung zu sein, die plausibel aussehen und trotzdem falsch liegen könnte.

Das ist der stille Vorteil von TOML gegenüber jedem tabellenförmigen Ziel für dieselbe Datei. Eine CSV-Datei, eine Parquet-Datei oder eine Reihe von INSERT-Statements muss Datensätze auf eine gemeinsame Spaltenmenge abgleichen und Lücken füllen, wo ein Datensatz nichts hatte. Ein Array von Tabellen tut das nicht: Jeder Block trägt genau die Schlüssel, die seine Zeile hatte.

Eine Datei, in der spätere Datensätze ein zusätzliches Feld gewinnen, wandelt sich also ohne NULL-Werte, ohne leere Zellen und ohne Verbreiterung. Das Ergebnis liest sich als das, was es ist — eine Liste weitgehend ähnlicher Datensätze — statt als dünn besetztes Raster. Für eine über die Zeit gewachsene Sammlung von Testdaten ist das meist die ehrlichere Darstellung.

TOML kennt kein Null-Literal, und der Schreiber erfindet keins. Ein Schlüssel, dessen JSON-Wert null war, wird schlicht nicht in den Block geschrieben, weder auf oberster Ebene eines Datensatzes noch tiefer darin.

Ob das etwas ausmacht, hängt vom lesenden Werkzeug ab. Viele behandeln einen fehlenden Schlüssel und einen leeren Wert gleich und fallen so oder so auf einen Standardwert zurück — für die ist nichts verloren. Wo die Unterscheidung Verhalten steuert, hat die Umwandlung die Daten still verändert, und der günstigste Schutz ist, die Quelle vor dem Umwandeln auf null zu durchsuchen, statt die beiden Dateien hinterher zu vergleichen — eine fehlende Zeile fällt deutlich schwerer auf als eine veränderte.

Ein Datensatz mit einem verschachtelten Objekt erzeugt darunter eine Sub-Tabelle: Ein Autor-Objekt in einem Datensatz wird zu einem [items.author]-Header mit seinen Schlüsseln darunter. Die Tiefe drückt sich im Header aus, nicht in der Einrückung, sodass selbst drei Ebenen auf der Seite flach bleiben.

Das ist auf beliebiger Tiefe zulässig und ab zwei oder drei Ebenen unangenehm zu lesen. Ein Header wie [items.metadata.source.system] ist gültig, aber niemand liest ihn gern, und eine Testdaten-Datei, die solche Header erzeugt, trägt meist mehr Struktur, als eine handgepflegte Datei tragen sollte. Das ist ein Hinweis auf die Daten, nicht auf die Umwandlung.

Ein TOML-Tabellenheader beansprucht jede danach folgende Zeile bis zum nächsten Header — ein einfacher Schlüssel unter einem Block würde also still Teil dieses Blocks werden. Der Schreiber setzt deshalb jeden Einzelwert auf oberster Ebene vor den ersten Header.

Bei diesem Paar kommt das selten vor, weil die Eingabe eine Liste ist und am Ende alles in einem Block landet. Beim späteren Bearbeiten der Datei zählt es dann: Einen version-Schlüssel unten in der Datei einzufügen, setzt ihn in den letzten Datensatz statt auf die oberste Ebene — der häufigste Fehler beim manuellen Umgang mit TOML. Solche Schlüssel gehören an den Anfang, vor den ersten doppelt geklammerten Header.

TOML 1.0 kennt vier Datums- und Zeittypen, darunter ein Offset-Datum-Zeit-Format als echten Wert statt als Text. JSON kennt keinen davon — jeder Zeitstempel in jeder JSON-Datei ist per Konvention eine Zeichenkette oder eine Zahl —, deshalb wird ein Wert wie „2024-01-01T00:00:00Z" als gequoteter TOML-String geschrieben.

Das ist korrekt und zugleich weniger, als das Format ausdrücken könnte. Will das lesende Werkzeug ein echtes Datum-Zeit-Objekt, genügt es, bei diesen Zeilen die Anführungszeichen zu entfernen — sonst muss an der Datei nichts geändert werden. Das lässt sich gut erledigen, während man ohnehin gerade die Block-Header umbenennt.

Ein paar Dutzend sind angenehm. Ein paar Hundert ergeben eine Datei, die niemand lesen wird, die ein Werkzeug aber weiterhin schnell verarbeitet. Ein paar Tausend Blöcke sind eine Konfigurationsdatei nur noch dem Namen nach, und an diesem Punkt gilt keine der Eigenschaften mehr, die TOML attraktiv machten — lesbare Diffs, manuelle Bearbeitung, Kommentare neben den Werten.

Diese Faustregel lohnt sich ehrlich anzuwenden: Wird die Datei ohnehin niemand öffnen, lohnt sich die Umwandlung in ein Konfigurationsformat nicht. CSV ist kleiner und wird von jedem Werkzeug gelesen, JSON ist das, was die Daten ohnehin schon waren, und eine Datenbank ist das Richtige, wenn die Liste später abgefragt werden soll. TOML verdient seinen Platz nur, wenn eine Person das Ergebnis tatsächlich pflegt.

Kommentare — der ganze Grund, warum Konfigurationsformate so aussehen, wie sie aussehen. JSON kennt keine, also auch keine zeilenweise Datei daraus, sodass die Gründe hinter den Werten einer Testdaten-Sammlung derzeit in einer Commit-Nachricht stehen oder in niemandes Kopf mehr.

Sobald die Datei TOML ist, können diese Gründe direkt neben den Einträgen stehen: warum dieser Datensatz aus einem Test ausgeschlossen ist, welche vorgelagerte Kennung ein Wert treffen muss, was kaputtgeht, wenn ein Eintrag umsortiert wird. Das ist Information, die eine generierte Datei nie hätte tragen können, und die ersten Minuten nach der Umwandlung sind der günstigste Zeitpunkt, sie aufzuschreiben.

Beide Hälften laufen als JavaScript in diesem Tab: Die Datei wird zeilenweise gelesen, und das TOML wird von einer kleinen, bei Bedarf nachgeladenen Bibliothek geschrieben. Nichts wird hochgeladen, es gibt kein Konto, und die kostenlose Stufe erlaubt bis zu 100 MB — eine Grenze, der bei einer Datei, für die diese Umwandlung passt, niemand nahekommt.

Der Datenschutz-Aspekt zählt trotzdem auch auf dieser Größenordnung. Eine Testdaten-Sammlung enthält oft echte Daten mit stehen gebliebenen Namen, und eine Seed-Datei für eine Entwicklungsdatenbank ist häufig ein Ausschnitt aus dem Produktivsystem. Sie nicht zu versenden ist hier eine kleinere Entscheidung als bei einer Log-Datei — und trotzdem die richtige.