JSON in TOML umwandeln

JSON kennt keine Kommentare. Das steht so in der Spezifikation und ist kein Versehen, und es ist der Hauptgrund, warum in JSON geschriebene Konfiguration im Alltag unangenehm zu pflegen ist: Warum ein Timeout genau 45 Sekunden beträgt, kann nirgendwo neben der 45 stehen. TOML hat Kommentare, und das ist meist der ganze Anlass für diese Umwandlung — bei einem Rust-Projekt mit Cargo.toml, einer Hugo-Website oder einem Python-Paket mit pyproject.toml.

Der zweite Grund ist die flachere Struktur. Eine drei Ebenen tiefe JSON-Konfiguration bedeutet drei Ebenen geschachtelter Klammern und entsprechend viel Einrückung; dasselbe in TOML ist eine Kopfzeile wie [server.tls.client] und darunter eine kurze Liste von Schlüsseln. An den Daten ändert sich nichts, aber der Diff, den ein Kollege im Review sieht, wenn sich ein Wert ändert, ist eine Zeile statt eines neu eingerückten Blocks.

Ein TOML-Dokument ist im Kern eine Tabelle. Es kann nicht, wie ein JSON-Dokument, mit einer eckigen Klammer beginnen, weil dafür schlicht keine Entsprechung existiert. Die Umwandlung löst das, statt mit einem Fehler abzubrechen: Ein Wert, der kein Objekt ist, wird unter einem Schlüssel namens items zusammengefasst, und die Ausgabe beginnt dann mit [[items]].

Das hält die Datei gültig, ist aber ein Platzhalter und keine endgültige Lösung. Kein Konverter kann wissen, ob das Werkzeug, das die Datei liest, diese Liste servers, plugins oder dependencies nennen will. Den Schlüssel in der ersten Zeile umzubenennen ist eine Ein-Wort-Änderung, und der Rest der Datei stimmt danach bereits.

Das ist der Punkt, den man vor jedem Commit prüfen sollte. TOML kennt kein Null-Literal, und der Schreiber erfindet keins: Ein Schlüssel, dessen JSON-Wert null war, wird schlicht nicht geschrieben. Aus {"a": null} wird eine leere Datei; aus einer Tabelle mit einem echten und einem leeren Schlüssel bleibt nur der echte übrig.

Ob das ein Problem ist, hängt vom lesenden Werkzeug ab. Viele Konfigurationsleser behandeln einen fehlenden Schlüssel genauso wie einen leeren — beide greifen auf einen Standardwert zurück, und dort ändert sich inhaltlich nichts. Andere unterscheiden beides, und dort verändert die Umwandlung still die Konfiguration. Die JSON-Datei vorher nach null zu durchsuchen ist zuverlässiger, als hinterher die beiden Dateien zu vergleichen, weil eine fehlende Zeile viel leichter zu übersehen ist als eine geänderte.

Das überrascht meist die, die TOML für die schwächere Ausdrucksform halten. Eine Liste von Datensätzen wird als wiederholte Tabellenüberschrift geschrieben: [[servers]] dreimal ergibt drei Server, jeder mit seinen eigenen Schlüsseln darunter. Es ist ausführlicher als ein JSON-Array und deutlich leichter zu bearbeiten, weil ein vierter Server bedeutet, fünf Zeilen zu kopieren, statt Klammern zu zählen.

Die Einträge müssen dabei nicht dieselben Schlüssel teilen. Ein Array, dessen erstes Objekt id und name hat und dessen zweites noch region ergänzt, wird ohne Beanstandung umgewandelt, und die TOML-Datei bleibt gültig — jeder Block trägt die Schlüssel, die er hat.

Eine TOML-Tabellenüberschrift beansprucht alles, was danach folgt, bis zur nächsten Überschrift. Ein einfacher Schlüssel nach [server] gehört also zu server, egal was ursprünglich gemeint war. Der Schreiber hebt deshalb jeden obersten Skalarwert über die erste Tabellenüberschrift: {"server": {"host": "localhost"}, "debug": true} wird zu debug = true, einer Leerzeile, dann [server] und host.

Die Ausgabe folgt also nicht der Reihenfolge der JSON-Datei, und das kann sie auch gar nicht. Es ist die einzige Umsortierung, die die Bedeutung erhält — jede andere würde verschieben, zu welcher Tabelle ein Schlüssel gehört. War die ursprüngliche Gruppierung aus Lesbarkeitsgründen wichtig, lässt sich das nur durch das Verschieben ganzer Tabellenblöcke wiederherstellen, nicht durch das Verschieben einzelner Zeilen.

Vier Ebenen JSON-Verschachtelung werden zu einer einzigen Kopfzeile: {"a":{"b":{"c":{"d":1}}}} wird zu [a.b.c] mit d = 1 darunter. TOML drückt Tiefe in der Überschrift aus statt in der Einrückung, weshalb eine stark strukturierte Konfiguration in TOML oft kürzer und flacher wirkt als das JSON, aus dem sie stammt.

Das hat auch eine Grenze, die eher eine Geschmacksfrage als eine Gültigkeitsfrage ist. Eine Überschrift wie [build.targets.linux.arm64.flags] ist zulässig, liest sich aber niemand gerne. Enthält die umgewandelte Datei Überschriften mit mehr als drei oder vier Segmenten, ist das meist ein Zeichen, dass die Konfiguration in mehrere Dateien oder Werkzeuge aufgeteilt gehört — und die Umwandlung hat dieses Problem nur sichtbar gemacht, nicht verursacht.

Die Ausgabe enthält keine Kommentare, weil die Eingabe keine hatte. JSON transportiert sie nicht, es gibt also nichts zu übersetzen — das ist keine Schwäche des Konverters, sondern der eigentliche Grund, warum sich der Wechsel überhaupt lohnt.

Damit sind die ersten fünf Minuten nach der Umwandlung der wertvollste Teil der Übung. Die TOML-Datei ist die Fassung dieser Konfiguration, die das Wissen tragen kann, das heute nur im Kopf eines Kollegen oder in einer Commit-Nachricht steckt: welche Werte gefahrlos geändert werden dürfen, welcher zu einem Wert in einem anderen Repository passen muss, warum ein Limit gerade an dieser Stelle liegt. Genau dieser Moment kostet nichts.

TOML kennt vier Datums- und Zeittypen, darunter ein Offset-Datum-Zeit-Wert als eigenständiger Typ statt als Zeichenkette. JSON kennt keinen davon: RFC 8259 gibt nur Zeichenketten, Zahlen, Wahrheitswerte, null, Arrays und Objekte her, und jeder Zeitstempel in jeder JSON-Datei ist per Konvention eine der ersten beiden Optionen.

Ein JSON-Wert "2024-01-01T00:00:00Z" wird deshalb als zitierte TOML-Zeichenkette geschrieben, was korrekt ist und weniger, als das Format ausdrücken könnte. Soll das lesende Werkzeug ein echtes Datum bekommen, entfernt man die Anführungszeichen an dieser Stelle von Hand — danach wird die Zeile als Datum geparst, ohne dass sich sonst etwas ändern muss.

Der günstigste Test ist ein Hin und Zurück: die TOML wieder zu JSON umwandeln und mit dem Ausgangspunkt vergleichen. Schlüssel, die null waren, fehlen — sonst sollte nichts abweichen, und aus einer vagen Sorge wird ein Diff, der sich in Sekunden lesen lässt.

Der zweite Test ist das Zielwerkzeug selbst. Cargo, Hugo und die meisten Python-Paketierungswerkzeuge melden sofort, ob das Dokument gültig ist und ob die Schlüssel dort stehen, wo sie erwartet werden — und finden damit genau das, was der Hin-und-zurück-Vergleich nicht findet: eine korrekt umgewandelte Datei, deren oberster Schlüssel noch items heißt, weil niemand ihn umbenannt hat.

Eine deutschsprachige Konfiguration mit Kommentaren wie „# Zeitüberschreitung in Sekunden" oder Feldnamen mit Umlauten funktioniert hier ohne Sonderbehandlung: Beide Seiten arbeiten mit UTF-8, und weder der JSON-Leser noch der TOML-Schreiber setzen eine andere Kodierung voraus. Wer Zeichenketten mit ä, ö, ü oder ß in den Werten hat, muss also nichts umstellen.

Was hier nicht passiert, ist eine Übersetzung der Feldnamen selbst — ein Schlüssel „zeitueberschreitung" bleibt „zeitueberschreitung". Das ist erwartbar, aber es lohnt sich, es zu erwähnen, weil einige Konfigurationswerkzeuge Schlüssel case-sensitiv oder mit festen Namen erwarten und eine Umwandlung daran nichts ändert.

In diesem Browsertab, auf dem eigenen Prozessor. Beide Hälften sind JavaScript — der JSON-Parser ist der im Browser eingebaute, der TOML-Schreiber eine kleine, bei Bedarf nachgeladene Bibliothek —, es geht also keine Anfrage mit der Datei irgendwohin, und es gibt weder Konto noch Warteschlange noch Tageslimit. Die kostenlose Nutzung akzeptiert Dateien bis 100 MB, eine Grenze, die bei Konfigurationsdateien praktisch niemand erreicht.

Das ist bei Konfiguration wichtiger als bei den meisten anderen Daten. Eine JSON-Konfigurationsdatei enthält häufig interne Hostnamen, Bucket-Namen, Dienstkonten und gelegentlich ein Zugangstoken, das eigentlich entfernt werden sollte — genau das wäre der Teil, der bei einem Upload zu einem fremden Webkonverter tatsächlich gegen interne Richtlinien verstoßen könnte. Hier gibt es nichts hochzuladen.