XML in TOML umwandeln

In vielen deutschen Unternehmen läuft die Konfiguration seit Jahren als XML, weil das Werkzeug, das sie liest, aus der Java-Welt stammt — ein Spring-Kontext, ein Maven-Build, ein internes Framework. Wechselt das Projekt zu einem Rust- oder Python-Werkzeug, verlangt das neue System plötzlich eine Cargo.toml oder eine pyproject.toml, und die alten Werte müssen dorthin.

Diese Seite übernimmt die Fleißarbeit: jeden Wert aus der XML-Datei in eine TOML-Tabelle mit passendem Namen zu übertragen. Was am Ende herauskommt, ist ein Rohentwurf, keine fertige Konfigurationsdatei — die Nacharbeit ist Teil dieser Seite und wird unten genau beschrieben.

Jedes Element mit Kindelementen wird zu einer Tabelle, geschrieben als eckige Klammer mit dem vollständigen, durch Punkte getrennten Pfad. Ein Element drei Ebenen tief erzeugt einen einzigen Kopf mit drei Namen statt drei verschachtelter Blöcke, weil TOML Tiefe im Kopf ausdrückt und nicht in der Einrückung.

Innerhalb einer Tabelle stehen einfache Werte zuerst, verschachtelte Tabellen danach — das ist die einzige Reihenfolge, die TOML zulässt, denn alles unter einem Kopf gehört zu ihm, bis der nächste Kopf beginnt. Die Ausgabe liest sich deshalb nicht in derselben Reihenfolge wie die XML-Datei; bei vielen kleinen Elementen fällt diese Umsortierung deutlich auf. Kein Wert wandert dabei an einen anderen Pfad, nur die Reihenfolge ändert sich.

Das ist der Teil der Umwandlung, der keine Nacharbeit braucht. Zwei oder mehr Geschwisterelemente mit demselben Tag werden zu einem TOML-Array von Tabellen, mit doppelt geklammertem Kopf, einmal pro Eintrag, in der Reihenfolge des Dokuments. Eine Liste von Abhängigkeiten, eine Liste von Servern, eine Liste von Regeln — all das landet genau in der Form, die eine TOML-Konfiguration ohnehin verwenden würde.

Der bekannte XML-Vorbehalt gilt trotzdem: Ein einzelnes Vorkommen eines wiederholbaren Elements wird kein Array, sondern eine einfache Tabelle mit einfach geklammertem Kopf. Dieselbe Datei mit einem Eintrag und mit zwei Einträgen ergibt strukturell unterschiedliche Ausgaben. Wer die Konfiguration in einem Repository versioniert, sollte diesen Unterschied kennen, bevor er als unerwarteter Diff auftaucht.

TOML erlaubt bei nicht in Anführungszeichen gesetzten Schlüsseln nur Buchstaben, Ziffern, Unterstriche und Bindestriche. Attribute kommen vom Parser als Schlüssel beginnend mit @, Elementtext als Schlüssel namens #text — beides sind keine erlaubten bloßen Schlüssel und werden deshalb in Anführungszeichen gesetzt. Das ist gültiges TOML, sieht aber genauso ungewohnt aus, wie es klingt.

Diese Schlüssel sind gleichzeitig eine Erledigungsliste. Ein gequoteter Schlüssel zeigt an, dass der Name aus der XML-Maschinerie stammt und nicht aus der eigentlichen Konfiguration — fast jeder davon sollte umbenannt werden: Aus einem @value-Attribut wird ein normaler Wertschlüssel, ein @xmlns-Schlüssel wird gelöscht, ein #text-Schlüssel bekommt den Namen dessen, was das Element tatsächlich enthielt.

Ein TOML-Dokument ist selbst eine Tabelle, und ein XML-Dokument hat genau ein Wurzelelement, also erscheint die gesamte Datei eine Ebene tiefer als gewünscht — unter einem einzigen Kopf, der nach der Wurzel benannt ist. Eine Datei mit dem Wurzelelement configuration erzeugt eine configuration-Tabelle, die alles Weitere umschließt.

Diese eine Ebene zu entfernen ist eine mechanische Änderung: den ersten Kopf löschen und dieses Segment aus jedem weiteren Kopf der Datei streichen. Der Aufwand lohnt sich, weil dadurch jeder Pfad in der Konfiguration eine Ebene kürzer wird und eine TOML-Datei über ihre Köpfe gelesen wird.

TOML kennt keinen Nullwert, und bei Umwandlungen aus Formaten, die einen kennen — YAML zum Beispiel — verschwinden Schlüssel manchmal still, wenn ihr Wert leer ist. Das kann hier nicht passieren, weil auch XML keinen Nullwert kennt: Ein leeres Element und ein selbstschließendes Element bedeuten dasselbe und werden beide zu einer leeren Zeichenkette.

Die Zusicherung ist also stärker als bei manchen Nachbardateiformaten: Jedes Element, das in der XML-Datei einen Wert hatte, hat auch in der TOML-Datei einen Schlüssel. Leere Zeichenketten übersieht man in einer langen Datei trotzdem leicht — beim Aufräumen einer Migration lohnt sich eine gezielte Suche danach.

TOML führt Datum und Uhrzeit direkt in der Kernspezifikation — Offset-Datumszeiten, lokale Datumszeiten, lokale Daten und lokale Uhrzeiten — und ein Parser gibt sie als echte Datumswerte zurück, nicht als Text. Der Umwandler liest zahlenartige XML-Werte zwar bereits als Zahl, ein Datum mit Bindestrichen zählt für ihn aber nicht dazu und bleibt Text — es kommt deshalb als gequotete Zeichenkette an und bleibt eine.

Diese Anführungszeichen von Hand zu entfernen macht daraus ein echtes TOML-Datum, und das dauert wenige Minuten. Genau die erwähnte Zahlenerkennung lohnt sich dagegen, im Ergebnis zu überprüfen: Ein als 1.0 geschriebener Versionswert wird als TOML-Ganzzahl 1 geschrieben — die Version hat ihre Form verloren, und das gehört zurück in Anführungszeichen.

Ein Element mit mehreren Textzeilen — eine Beschreibung, ein Lizenztext, ein eingebettetes Skript — wird zu einer einzigen TOML-Zeichenkette mit \n-Escapes an der Stelle der Zeilenumbrüche. Das ist korrekt und unleserlich, und es widerspricht dem eigentlichen Zweck, überhaupt in ein von Hand editierbares Format zu wechseln.

TOML hat eine mehrzeilige Zeichenkettensyntax mit dreifachen Anführungszeichen, die genau solche Werte lesbar hält, aber der Schreiber nutzt sie nicht. Die Werte mit Escapes im Ergebnis suchen und jeweils als dreifach gequoteten Block umschreiben ist eine schnelle Korrektur — bei mehreren solchen Werten in einer Datei ist das oft ein Hinweis, dass der Inhalt besser in eine eigene Datei gehört.

Kommentare fallen weg, obwohl beide Formate sie kennen, sodass die Erklärungen aus der alten Datei in der neuen nicht mehr auftauchen. Namensräume verlieren ihre Bedeutung, sobald ihre Präfixe zu bloßen Zeichen in einem Schlüsselnamen werden. Und das Schema fällt weg: XML lässt sich vor dem Start einer Anwendung gegen eine XSD prüfen, TOML kennt in seiner Spezifikation keine Schemasprache.

Das letzte ist die Abwägung, die bewusst getroffen werden sollte. TOML ist leichter zu lesen, leichter von Hand zu schreiben und eindeutig bei den Typen — und gibt dafür die Möglichkeit auf, eine fehlerhafte Konfiguration maschinell abzulehnen. Wurde die XML-Datei tatsächlich validiert, verschwindet diese Prüfung mit der Umstellung, und sie durch einen Check beim Programmstart zu ersetzen gehört zur Migration dazu.

Das Werkzeug liefert jeden Wert aus der XML-Datei, in der passenden Tabelle, in den meisten Fällen mit dem richtigen Namen und im Rest mit einem gequoteten, offensichtlich falschen Namen. Das ist ein guter Ausgangspunkt und noch keine fertige Konfigurationsdatei.

Die Arbeit danach ist überschaubar und nicht optional: die Wurzeltabelle entfernen, die @- und #text-Schlüssel umbenennen, Datumswerte von den Anführungszeichen befreien, mehrzeilige Werte umschreiben, Kommentare aus dem Original übertragen. Bei einer großen Datei ist das eine Stunde Arbeit — sie zu überspringen ergibt eine TOML-Datei, die funktioniert, aber niemandem, der sie später liest, als absichtlich geschrieben vorkommt.

Wer beruflich mit Rust arbeitet, kennt TOML meist schon aus der Cargo.toml jedes Projekts, und wer mit Hugo eine statische Website baut — im deutschsprachigen Blogging- und Dokumentationsumfeld weit verbreitet — schreibt Frontmatter und Konfiguration ebenfalls in diesem Format. Die Umstellung einer alten XML-Konfiguration betrifft also selten ein Team, das TOML zum ersten Mal sieht, sondern eines, dessen übrige Werkzeuge längst darauf eingeschworen sind und dessen letzte XML-Datei die einzige Ausnahme im Projekt ist.

Das erklärt auch, warum diese Migration meist keine grundsätzliche Diskussion mehr auslöst. Die Frage ist nicht mehr, ob TOML das richtige Format ist, sondern nur noch, wie schnell sich die letzte verbliebene XML-Datei in die gleiche Form bringen lässt wie alles andere im Repository.

Eine XML-Konfiguration, die es wert ist, migriert zu werden, enthält häufig genau die Werte, die niemand in einen fremden Onlinedienst eingeben möchte: Datenbank-Verbindungszeichenfolgen mit Passwort, API-Schlüssel, interne Hostnamen. Der Parser und der TOML-Schreiber laufen beide als JavaScript in diesem Tab, sodass eine solche Datei die eigene Maschine zu keinem Zeitpunkt verlässt.

Für ein Unternehmen mit eigener IT-Sicherheitsrichtlinie ist das oft die eigentliche Voraussetzung dafür, ein Werkzeug wie dieses überhaupt einsetzen zu dürfen — ein Konverter, der die Datei zuerst auf einen Server schickt, fiele in vielen Häusern schon aus formalen Gründen durch die interne Freigabe, unabhängig davon, wie gut er die Umwandlung sonst beherrscht.

Bei einer Migration mit mehreren XML-Dateien lohnt es sich, zunächst nur die kleinste oder unkritischste umzuwandeln und das Ergebnis vollständig durchzuarbeiten — Wurzeltabelle entfernen, Schlüssel umbenennen, Datumswerte prüfen —, bevor der Rest folgt. Wer stattdessen gleich zwanzig Dateien auf einmal umwandelt, sammelt zwanzig Mal dieselbe Nacharbeit an, ohne aus der ersten Datei gelernt zu haben, welche Muster im eigenen Projekt am häufigsten vorkommen.

Aus der ersten Datei lässt sich meist ableiten, welche Attributnamen im Projekt wiederkehren und welche Umbenennung sich lohnt, bevor sie ein zweites Mal ansteht. Das macht aus einer mechanischen Fleißaufgabe eine Migration mit Muster, statt zwanzig Einzelfälle unabhängig voneinander zu bearbeiten.