YAML in XML umwandeln

Der Anlass für diese Umwandlung ist fast immer eine Vorgabe von außen. Ein deutsches Behördenverfahren, das nach einem XÖV-Standard integriert, eine Schnittstelle im automobilen Zulieferwesen, die VDA-XML erwartet, oder eine ältere Middleware, deren Vertrag ein XSD ist und kein JSON-Schema. Das eigene Team schreibt Konfiguration und Testdaten längst in YAML, weil sich das ohne Anführungszeichen tippen lässt — die Gegenstelle liest davon nichts.

Diese Ausgangslage entscheidet, was ein gutes Ergebnis ist. Es geht nicht darum, dass die XML-Datei elegant aussieht, sondern darum, dass sie exakt die Form annimmt, die das Schema am anderen Ende verlangt. Genau dafür sind Elemente allein zu wenig — die meisten realen Schemas verlangen auch Attribute, und dieser Konverter bietet einen Weg, sie gezielt zu erzeugen.

Jeder Schlüssel wird zu einem Element, sein Wert zum Inhalt dieses Elements. Eine verschachtelte Zuordnung wird zu einem verschachtelten Element, ein Skalar zu Text zwischen öffnendem und schließendem Tag. An der Übersetzung ist nichts raffiniert, und genau das will man, wenn das Ergebnis gegen eine fremd geschriebene Spezifikation bestehen muss.

Werte werden als Text geschrieben, weil ein XML-Element nichts anderes fassen kann. Eine YAML-Zahl, im Quelltext als 1.50 notiert, kommt als 1.5 heraus, weil der Parser die Nachkommazahl vorher schon in eine Zahl aufgelöst und die überflüssige Null dabei verworfen hat. Wird dieselbe Zahl im deutschen Format mit Komma geschrieben, 1,50, erkennt der YAML-Parser darin gar keine Zahl — Komma ist kein gültiges Dezimaltrennzeichen in YAML —, der Wert bleibt eine Zeichenkette und kommt unverändert als 1,50 heraus. Verlangt das empfangende Schema eine bestimmte Schreibweise — eine Dezimalzahl mit fester Nachkommastelle, ein Datum mit Zeitzone —, muss der Wert in der YAML-Datei als Zeichenkette in Anführungszeichen stehen, damit er unverändert durchkommt.

XML verlangt genau ein äußerstes Element, ein YAML-Dokument kann mehrere Schlüssel auf oberster Ebene haben. Die Regel: Ein einzelner oberster Schlüssel wird zur Wurzel, egal was er enthält — außer es ist eine Liste. Ein Dokument mit dem einzigen Schlüssel bestellung wird also zu einem bestellung-Wurzelelement, ein Dokument mit drei obersten Schlüsseln bekommt eine generische Hülle mit drei Kindern.

Der Fall, der Integrationsteams überrascht, ist ein einzelner oberster Schlüssel, dessen Wert eine Liste ist — auch der bekommt die generische Hülle, denn den Schlüssel selbst als Wurzel zu nehmen, würde das Tag einmal pro Listenelement wiederholen und ein Dokument mit mehreren äußersten Elementen ergeben, was kein gültiges XML ist. Verlangt das Zielschema einen bestimmten Wurzelnamen — bei einer Anbindung an ein XÖV-Verfahren steht der meist fest —, gehört genau ein oberster Schlüssel mit diesem Namen in die YAML-Datei, und alles Weitere darunter.

Eine YAML-Sequenz unter einem Schlüssel erzeugt diesen Schlüssel einmal pro Eintrag. Drei Positionen unter einem Schlüssel namens position werden zu drei position-Elementen nebeneinander. Das ist das ältere und verbreitetere XML-Idiom, und es entspricht dem, was ein XSD mit maxOccurs="unbounded" erwartet.

Es ist nicht das einzige. Viele Schemas — gerade in deutschen Verwaltungs- und Industriestandards — wollen eine Plural-Hülle mit Singular-Kindern darin, etwa ein positionen-Element mit mehreren position-Kindern. Aus einer einfachen Liste erzeugt dieser Konverter das nicht von selbst. Man bekommt es, indem man die YAML entsprechend schachtelt: ein Schlüssel positionen, dessen Wert eine Zuordnung mit einem einzigen Schlüssel position ist, der die Liste hält. Die Schachtelung in der Quelle bestimmt die Schachtelung in der Ausgabe.

Reine Element-XML ist für Daten in Ordnung und für die meisten realen Schemas falsch, die Kennungen, Typen oder Sprachcodes in Attribute legen. Zwei Schlüsselnamen geben Kontrolle darüber. Ein Schlüssel, dessen Name mit @ beginnt, wird zum Attribut des umschließenden Elements, das @ wird dabei entfernt. Ein Schlüssel namens #text wird zum eigenen Textinhalt des Elements.

Ausformuliert: Eine YAML-Zuordnung namens auftrag mit "@id" gleich 42, "@status" gleich offen und einem Schlüssel kunde ergibt ein auftrag-Element mit den Attributen id und status sowie einem kunde-Kind darin. "@lang" und "#text" in derselben Zuordnung ergeben ein einzelnes Tag mit Attribut und Text, ohne Kinder. Beide Schlüssel müssen in der YAML-Datei in Anführungszeichen stehen, denn @ am Anfang eines nicht zitierten Skalars ist reserviert und # würde einen Kommentar einleiten.

XML-Elementnamen erlauben Buchstaben, Ziffern, Unterstriche, Bindestriche und Punkte und dürfen nicht mit einer Ziffer beginnen. YAML-Schlüssel erlauben praktisch alles. Jedes Zeichen, das der Writer nicht verwenden kann, wird zu einem Unterstrich, und ein mit einer Ziffer beginnender Name bekommt einen vorangestellt — aus "mein schlüssel" wird mein_schl_ssel, aus "2te position" wird _2te_position.

Diese Ersetzung verliert Information und kann kollidieren: Zwei Schlüssel, die sich nur im verbotenen Zeichen unterscheiden, landen am Ende auf demselben Elementnamen. Bindestriche und Punkte laufen unverändert durch, ein Schlüssel wie build-schritt oder werkzeug.version kommt also so an, wie er getippt wurde. Benennt das Zielschema die Elemente vor, ist es der sicherere Weg, die YAML-Schlüssel vor der Umwandlung anzupassen, statt das XML danach zu reparieren.

Es gibt keine XML-Deklaration, die Datei beginnt direkt mit dem ersten Tag. Es gibt kein DOCTYPE, keine Namensraum-Deklaration und keinen Schema-Verweis. Die Ausgabe ist UTF-8 und wohlgeformt, sagt aber selbst nichts darüber, zu welchem Vokabular sie gehört.

Für eine Anbindung ist das meist eine kleine, von Hand zu schließende Lücke: eine Deklarationszeile, ein xmlns-Attribut an der Wurzel, ein Schema-Verweis. Das xmlns-Attribut lässt sich einfach an der Quelle ergänzen, denn es ist nur ein weiterer Schlüssel mit @-Präfix in der obersten Zuordnung der YAML — dann überlebt der Namensraum jede künftige Umwandlung, statt jedes Mal neu ergänzt werden zu müssen.

Ein YAML-Schlüssel ohne Wert wird zu einem leeren Elementpaar. XML unterscheidet das nicht von einem Element mit leerer Zeichenkette — behandelt das empfangende Schema abwesend und leer unterschiedlich, gehört der Schlüssel eher ganz aus der YAML entfernt, statt ihn ohne Inhalt stehen zu lassen.

Kaufmännisches Und, spitze Klammern und doppelte Anführungszeichen in einem Wert werden maskiert, sodass etwa eine URL mit Query-Parametern sicher durchkommt, statt das Dokument zu brechen. Ein mehrzeiliger Blockskalar wird mit seinen Zeilenumbrüchen im Element geschrieben, was gültiges XML ist — ob der empfangende Parser diese Leerzeichen erhält, hängt vom Schema ab, wer darauf angewiesen ist, sollte den Wert selbst in einen CDATA-Abschnitt legen.

XML ist seit 1998 eine W3C-Empfehlung, und der Grund, es statt JSON auszuliefern, ist fast nie die Syntax, sondern das Ökosystem: ein XSD, das ein fehlerhaftes Dokument abweist, bevor es eine Anwendung erreicht, XPath, um einen einzelnen Wert aus einem großen Dokument zu holen, XSLT für die Umformung, XML-Signaturen, wo eine Gegenstelle beweisen muss, dass ein Dokument unverändert ist.

Nichts davon kommt mit der Umwandlung automatisch. Die Ausgabe sofort gegen das Schema zu prüfen, an der ersten Datei, bevor eine ganze Pipeline darauf aufgebaut wird, ist der Schritt, der sich am meisten auszahlt — ein Element, das eigentlich ein Attribut hätte sein sollen, ist in der YAML eine Änderung von zwei Zeichen und nach dem Aufbau einer Pipeline ein langer Nachmittag.

Zwei Probleme an der Quelle stoppen die Umwandlung, statt sie nur zu verschlechtern. Eine Datei mit --- Trennzeichen enthält mehrere YAML-Dokumente, eine XML-Datei genau eines — der Parser lehnt ab, statt zu wählen. Aufteilen und jedes Dokument einzeln umwandeln ist der Weg. Ein doppelter Schlüssel in derselben Zuordnung wird ebenfalls zurückgewiesen, mit Zeilennummer — strenger als manches YAML-Tooling, und zu Recht: Ein doppelter Schlüssel bedeutet, dass eine der beiden Einstellungen seit ihrer Einführung ignoriert wurde.

Kommentare stoppen nichts und überleben auch nicht. Beide Formate kennen sie, keiner deiner Kommentare kommt herüber — die XML-Datei trägt die Daten, nicht die Begründung dahinter. Die YAML als Quelle der Wahrheit zu führen, das XML als erzeugtes Artefakt zu behandeln und es nie von Hand zu bearbeiten, ist die Arbeitsweise, für die diese Umwandlung gedacht ist.