TOML in XML umwandeln

Der interessante Fall ist keine Formatvorliebe. Die Fakten über eine Software — Abhängigkeiten, Version, Lizenz — stehen in einer TOML-Datei, weil sich Cargo, pip und ein gutes Stück des modernen Werkzeugkastens dafür entschieden haben. Das System, das diese Fakten aufnehmen soll, liest seit Jahren XML: ein internes Lizenzregister, ein Compliance-Import für die Software-Stückliste, ein Meldeportal, das seit seiner Einführung keinen zweiten Dateityp gelernt hat.

Aus dieser Einordnung folgt, wie der Rest der Seite zu lesen ist. Es geht nicht um eine originalgetreue Abbildung von TOML in XML, denn auf der Gegenseite interessiert sich niemand für TOML. Es geht darum, wie nah die Ausgabe an ein fremd definiertes Dokument herankommt und welche der Lücken von Hand geschlossen werden müssen — es sind fünf, und jede hat unten einen eigenen Abschnitt.

XML braucht genau eine Wurzel, ein TOML-Dokument ist eine Tabelle mit beliebig vielen Schlüsseln, also greift eine Regel. Hat die Datei genau einen Schlüssel auf oberster Ebene, wird dieser Schlüssel zur Wurzel: Eine Datei mit nur einem [tool]-Abschnitt und dessen Unterabschnitten wird zu einem <tool>-Dokument. Gibt es mehrere Schlüssel auf oberster Ebene — der Normalfall bei einem Manifest mit [package] und [dependencies] und ein paar losen Werten —, landet alles in einem generischen <root>.

Dieses <root> umzubenennen ist fast immer die erste Änderung, und sie kostet nur zwei Zeichen an Anfang und Ende. Wiederholt sich die Umwandlung regelmäßig, ist es der sauberere Weg, das ganze Manifest unter einer Tabelle mit dem vom Zielschema gewünschten Namen zu bündeln — dann liefert der Konverter die richtige Wurzel jedes Mal von selbst.

Ein dreifach wiederholter [[bin]]-Block ist TOMLs Art, eine Liste von Datensätzen zu schreiben, und wird zu drei gleichrangigen <bin>-Elementen mit jeweils eigenen Kindelementen. Genau so stellt XML eine Liste dar, ohne Hüllelement und ohne Indexattribut — die einzige Stelle in dieser Umwandlung, an der nichts entschieden werden muss.

Ein einfaches Array aus Skalaren verhält sich gleich: tags = ["a", "b"] wird zu zwei <tags>-Elementen mit Textinhalt, nicht zu einem Element mit einer kommagetrennten Zeichenkette. Ob das Zielschema genau das oder ein umschließendes <tags> um <tag>-Kindelemente will, verrät eine XSD sofort, und ein XSLT-Schritt, der das Hüllelement einfügt, ist eine Sache von wenigen Zeilen.

TOML führt ungewöhnlicherweise vier Zeittypen statt eines einzigen, und die Umwandlung hält sie auseinander, statt sie auf einen einzigen UTC-Zeitpunkt zusammenzufassen. Aus launch = 2026-03-01T08:00:00Z, opens = 2026-03-01T08:00:00+02:00, seen = 2026-03-01T08:00:00, day = 2026-03-01 und at = 08:00:00 werden, in dieser Reihenfolge, <launch>2026-03-01T08:00:00.000Z</launch>, <opens>2026-03-01T08:00:00.000+02:00</opens>, <seen>2026-03-01T08:00:00.000</seen>, <day>2026-03-01</day> und <at>08:00:00.000</at>.

Das ist die Zuordnung, mit der ein Schema geschrieben oder gelesen werden muss: Die ersten drei sind lexikalisch gültiges xs:dateTime, das vierte xs:date, das fünfte xs:time. Die vier Werte mit einer Uhrzeit gewinnen dabei einen Millisekundenanteil, den sie im Manifest nicht hatten — 08:00:00 wird zu 08:00:00.000, und das reine Datum bleibt ohne Uhrzeit und damit ohne diesen Zusatz. xs:dateTime und xs:time akzeptieren Sekundenbruchteile, die Validierung ist also unberührt, aber ein XSLT-Vergleich gegen einen kurz geschriebenen Literalwert schlägt genau an dieser Stelle fehl.

Der Offset wird exakt so übernommen, wie er geschrieben wurde, nicht normalisiert: 2026-03-01T08:00:00+02:00 kommt als 2026-03-01T08:00:00.000+02:00 an, nicht als 06:00:00.000Z. Für ein Dokument, das jemand liest, ist das die bessere Wahl, bedeutet aber auch, dass zwei Elemente mit demselben Zeitpunkt unterschiedlichen Text tragen können.

Die unzonierten Werte sind der Punkt, über den vor dem Absenden nachzudenken lohnt. Ein lokaler TOML-Zeitstempel sagt, dass die Uhr irgendwo acht Uhr morgens zeigte, und das XML wiederholt das, ohne zu sagen wo — XSD nennt das zeitzonenunbestimmt. Die lokale Uhrzeit ist die schärfere Überraschung: at = 08:00:00 hat gar kein Datum, ein als xs:dateTime deklariertes Element weist den Wert also zurück, und in der Quelle steht nichts, um das fehlende Datum zu ergänzen. Entweder das Element als xs:time deklarieren, oder das Datum dort in der TOML ergänzen, wo es hingehört.

TOML erlaubt fast jeden Schlüssel, sofern er in Anführungszeichen steht: "2024 report", "line-length", "x:y". XML-Elementnamen dürfen nicht mit einer Ziffer beginnen und weder ein Leerzeichen noch, ohne deklarierten Namespace, einen Doppelpunkt enthalten. Der Schreiber schreibt um, statt abzulehnen: Alles außerhalb von Buchstaben, Ziffern, Unterstrich, Bindestrich und Punkt wird zum Unterstrich, und ein Name, der nicht mit einem Buchstaben oder Unterstrich beginnt, bekommt einen vorangestellt.

So wird "2024 report" zu <_2024_report>, "a b" zu <a_b> und "x:y" zu <x_y>. Der letzte Fall verdient besondere Aufmerksamkeit: Ein Schlüssel mit Doppelpunkt, gedacht als Namespace-Präfix, verliert diesen Doppelpunkt und wird zu einem gewöhnlichen Namen — nicht das, was ein Schema an dieser Stelle erwartet. Bindestrich und Punkt überstehen die Umwandlung dagegen unverändert.

Standardmäßig wird jeder TOML-Schlüssel zu einem Kindelement, und die meisten Schemas wollen zumindest einige Werte lieber als Attribut. Die Konvention dafür ist ein vorangestelltes At-Zeichen im Schlüsselnamen: In einer Tabelle erzeugt "@id" = 42 ein id="42" auf dem umschließenden Element statt eines <id>-Kindelements. TOML erlaubt den Schlüssel, weil er in Anführungszeichen steht.

Textinhalt neben Attributen nutzt auf dieselbe Weise den Schlüssel "#text". Beides lohnt sich zu kennen, weil es aus einem zweistufigen Vorgang einen einzigen macht — das TOML mit ein paar At-Zeichen umzugestalten geht schneller und wiederholt sich zuverlässiger als eine nachträgliche XSLT-Verschiebung. Attributwerte werden für kaufmännisches Und, spitze Klammern und Anführungszeichen maskiert und sind damit für eine Versionsnummer oder eine URL sicher.

Keine XML-Deklaration, das Dokument beginnt direkt bei der Wurzel. Kein Namespace, keine Schema-Referenz, keine Processing Instruction. Die Ausgabe ist mit zwei Leerzeichen pro Ebene eingerückt und endet mit einem Zeilenumbruch. Text und Attributwerte sind für &, <, > und " maskiert.

Ein leeres TOML-Array ist die andere leise Stelle: tags = [] erzeugt kein Element, nur eine Leerzeile dort, wo eines gewesen wäre — nachvollziehbar, weil kein Wert zu wiederholen ist, aber überraschend für ein Schema mit minOccurs="1" an dieser Stelle. Zwischen dem generischen <root>, den umgeschriebenen Elementnamen und dieser Lücke ist die ehrliche Zusammenfassung: Diese Umwandlung bringt die Datei weit, aber selten schon vollständig zur Gültigkeit.

Beide Formate kennen Kommentare, und weder Leser noch Schreiber übertragen sie — jede #-Zeile, die erklärt, warum eine Abhängigkeit fixiert ist oder warum ein Wert ungewöhnlich ausfällt, fehlt im XML. In einem Manifest ist das kein kleiner Verlust, dort stehen die Kommentare oft als einzige Aufzeichnung einer Entscheidung.

Das XML gehört deshalb als erzeugtes Artefakt behandelt, nicht als Kopie. Bei jeder Änderung des Manifests neu erzeugen, statt es zu bearbeiten und zu hoffen, dass beide synchron bleiben — und außerhalb des Repositorys halten, wenn der Einreichungsprozess keine eingecheckte Kopie verlangt.

Alles bisher Genannte ist ein Grund, warum der erste Versuch nicht valide sein wird: Die Wurzel trägt den falschen Namen, eine lokale Uhrzeit erfüllt kein als xs:dateTime deklariertes Element, manche Werte stehen als Kindelement, wo das Schema ein Attribut will, und eine optionale Liste kann ganz fehlen. All das in einem Durchgang zu finden, ist deutlich schneller als in vier Ablehnungs-Mails.

„xmllint --schema vertrag.xsd out.xml --noout" liefert die vollständige Liste der Beanstandungen mit Zeilennummer und läuft auf fast jedem Rechner. Die Punkte am Manifest beheben statt am XML, dann startet der nächste Durchgang von einer besseren Stelle. Bei einem wirklich komplexen Schema — verschachtelte Namespaces, Substitutionsgruppen, gemischter Inhalt — ist diese Umwandlung die Eingabe für eine XSLT, kein fertiges Dokument, und das von Anfang an so zu behandeln erspart eine spätere Diskussion.