TOML in JSON umwandeln

In vielen deutschen Firmen läuft die Continuous-Integration-Pipeline selbst gehostet auf GitLab, und die Skripte darin greifen gern zu Bordmitteln: jq für JSON, ein Shell-Skript für den Rest. Für ein `pyproject.toml` oder ein `Cargo.toml`, aus dem eine Versionsnummer oder eine Abhängigkeit ausgelesen werden soll, fehlt in so einer Pipeline meist ein TOML-Parser, den niemand extra installieren will, nur für eine Zeile Konfiguration.

Genau dafür ist diese Umwandlung gedacht: TOML bleibt die maßgebliche Quelle im Repository, JSON ist das, was die Pipeline tatsächlich liest. Die beiden Datenmodelle überlappen sich fast vollständig — eine Tabelle mit Schlüssel-Wert-Paaren, Verschachtelung und Arrays entspricht in JSON genau einem Objekt mit Verschachtelung und Arrays.

Ein in Klammern gesetzter Header wird zu einem verschachtelten Objekt, ein Header mit Punkten mehrere Ebenen tief — ein Header für ein Werkzeug und darunter eine Konfiguration für einen Linter ergibt ein Objekt im Objekt, dessen Pfad genau dem Header entspricht.

Ein doppelt geklammerter Header steht für ein Array von Tabellen und wird zu einem JSON-Array von Objekten, mit einem Eintrag je Vorkommen. Das trägt die Autorenliste eines Python-Pakets, die Binaries eines Rust-Crates oder die Ziele eines Builds, und ist genau die Konstruktion, über die man sich am meisten Sorgen macht und am wenigsten Sorgen machen muss — die Reihenfolge bleibt erhalten.

TOML ist das einzige Format in dieser Gruppe mit echten Zeittypen: Datum mit Zeitzone, lokales Datum mit Zeit, reines Datum, reine Uhrzeit — alles ist in der Spezifikation vorgesehen, ein Parser gibt sie als Datumsobjekte zurück. JSON kennt keinen einzigen davon, jeder wird zur Zeichenkette.

Die Werte bleiben dabei erhalten, mit einer Besonderheit: Ein Zeitstempel mit Zeitzone behält seine Zeitzone, statt auf UTC normalisiert zu werden. Eine reine Uhrzeit bekommt einen Millisekunden-Anteil, den sie vorher nicht hatte — aus acht Uhr morgens wird eine Zeichenkette mit angehängtem Bruchteil. Vergleicht eine nachgeschaltete Prüfung diese Zeichenketten direkt, statt sie zu parsen, ist genau dieser Anhang die Stelle, an der der Vergleich scheitert.

TOML 1.0 verlangt von einer Implementierung 64-Bit-Ganzzahlen. JSON-Zahlen sind IEEE-Gleitkommawerte und exakt nur bis etwa neun Billiarden. Eine TOML-Datei mit einer Ganzzahl darüber ist vollkommen gültig, und der hier verwendete Parser bricht mit einer Fehlermeldung ab, statt eine JSON-Datei mit einer falschen Zahl zu erzeugen.

Das Abbrechen ist die richtige Entscheidung. Eine still gerundete Kennung ist ein Fehler, der erst Wochen später auffällt, wenn ein Datenbankabgleich nichts mehr findet. Enthält die TOML-Datei einen Wert dieser Größenordnung — eine Snowflake-ID, eine große Seriennummer, einen Zeitstempel in Nanosekunden als Ganzzahl —, hilft es, ihn in der Quelle als Zeichenkette zu schreiben. Er war ohnehin nie eine Menge, und als Zeichenkette wird er in jedem nachgelagerten Schritt korrekt behandelt.

TOML-Gleitkommazahlen kennen `inf` und `nan` als eigene Werte. JSON kennt keinen von beiden, und der hier verwendete Serialisierer schreibt in beiden Fällen `null` — Standardverhalten in JavaScript, und verlustbehaftet auf eine Weise, die nirgends gemeldet wird: Eine konfigurierte Obergrenze von Unendlich und eine gar nicht gesetzte Obergrenze werden im JSON identisch.

Der feinere Verlust betrifft die Typisierung. TOML unterscheidet eine Ganzzahl von einer Fließkommazahl, `1` und `1.0` sind unterschiedliche Werte mit unterschiedlichem Typ, worauf sich ein Schema oder eine Anwendung verlassen kann. JSON kennt nur einen Zahlentyp, `1.0` wird als `1` geschrieben. Braucht ein Konsument die Information, dass ein Wert als Fließkommazahl deklariert war, muss sie auf einem anderen Weg mitgegeben werden — in der Datei steht sie nicht mehr.

Tabellen und Schlüssel erscheinen in der Reihenfolge, in der die TOML-Datei sie deklariert hat, was eine umgewandelte Datei lesbar hält und einen Vergleich zwischen zwei Umwandlungen aussagekräftig macht. Die Ausgabe ist mit zwei Leerzeichen eingerückt und endet mit einem Zeilenumbruch.

Die Ausnahme betrifft numerische Schlüssel. Ein in Anführungszeichen gesetzter TOML-Schlüssel, der eine Zahl ist — das kommt in Konfigurationen vor, die nach Jahr oder nach Port indizieren — wird vor alle anderen Schlüssel seines Objekts gestellt und aufsteigend sortiert, weil JavaScript-Objekte ganzzahlig aussehende Schlüssel so ordnen. Es ist der einzige Fall, in dem die Reihenfolge im JSON von der Quelle abweicht.

Die Ausgabe ist gewöhnliches JSON, jq liest sie ohne besondere Optionen: die Projektversion auslesen, Abhängigkeitsnamen auflisten oder prüfen, ob ein Werkzeugabschnitt existiert, sind alles einzeilige Ausdrücke. Das ist meist der ganze Grund für den Umweg, und aus einem Shell-Skript, das bisher mit `grep` in einer TOML-Datei suchte, wird eines, das sie richtig abfragt.

Das öffnet auch den Weg zur Validierung. JSON Schema ist ausgereift und weit verbreitet, TOML hat keine eigene Schemasprache in seiner Spezifikation, und Umwandeln mit anschließender Validierung ist ein echter Weg, um Hausregeln über viele Repositories hinweg durchzusetzen — jedes Paket muss eine Lizenz angeben, jedes Crate seine Edition festlegen —, was sich gegen die TOML-Datei direkt nicht prüfen ließe.

TOML unterstützt Kommentare und nutzt sie ausgiebig: der Grund, warum eine Abhängigkeit auf eine bestimmte Version festgelegt ist, die Ticketnummer neben einem Workaround, der Block, der erklärt, für welche Umgebung eine Einstellung gilt. JSON kennt nach RFC 8259 keine Kommentarsyntax, also kommt nichts davon an.

Das entscheidet die Richtung des Verhältnisses. Die TOML-Datei ist das, was Menschen bearbeiten und im Review lesen, das JSON entsteht daraus, wann immer etwas es einlesen muss. Beide Fassungen im Repository einzuchecken erzeugt zwei Wahrheiten, die auseinanderlaufen; das JSON im Build-Schritt zu erzeugen tut das nicht.

Soll eine Hausregel — jedes Paket muss eine Lizenz nennen, jedes Crate seine Edition festlegen — über viele Repositories hinweg geprüft werden, lassen sich bis zu 100 TOML-Dateien gleichzeitig ablegen, jede bis 100 MB, und alle JSON-Fassungen kommen als ein ZIP zurück. Ein Skript, das anschließend gegen ein Schema prüft, iteriert einfach über die entpackten Dateien.

Für eine einzelne Datei ist das ohnehin die schnellere Route, für einen Bestand aus zwanzig oder dreißig Repositories spart der Stapelvorgang, jede Konfigurationsdatei einzeln aufzurufen.

Findet das Lesen innerhalb einer Anwendung statt und nicht in einem CI-Schritt, ist ein Parser der richtige Weg. Praktisch jede größere Sprache hat einen: Python bringt `tomllib` seit einigen Versionen in der Standardbibliothek mit, Rust, Go und JavaScript haben ausgereifte Bibliotheken. Die Datei direkt zu lesen erhält die Zeittypen und die Unterscheidung zwischen Ganzzahl und Fließkommazahl, die diese Umwandlung einebnet.

Der Umwandler verdient seinen Platz an der Schnittstelle: eine einmalige Prüfung, ein CI-Schritt, in dem eine zusätzliche Abhängigkeit mehr Aufwand wäre als sie wert ist, oder eine Pipeline, deren nächste Stufe ausschließlich JSON spricht. Alles läuft im Browser, eine private Konfiguration mit einem Registry-Token darin lässt sich also gefahrlos hier ablegen, und die kostenlose Obergrenze von 100 MB liegt weit über jeder Konfigurationsdatei.