JSON in XML umwandeln

Ein deutsches Unternehmen, das eine Rechnung als XRechnung oder ZUGFeRD einreichen muss, ein Datenaustausch mit DATEV, eine Meldung an eine Behörde über eine SOAP-Schnittstelle, eine Schnittstelle zur Finanzverwaltung — an diesen Stellen war XML zuerst da, und JSON kam als bequemeres Format erst später dazu. Wer die Daten heute als JSON vorliegen hat, muss sie trotzdem in der älteren Sprache abliefern.

Diese Umwandlung übersetzt die Struktur, nicht die Bedeutung. Objekte werden zu verschachtelten Elementen, Listen werden zur gleichen Elementbezeichnung mehrfach hintereinander, und Schlüssel mit einem vorangestellten @ werden zu Attributen. Was dabei nicht entsteht, ist Schemakonformität — dazu gleich mehr.

Ein XML-Dokument hat genau ein äußerstes Element. Ein JSON-Dokument kann ein Objekt mit fünfzehn Schlüsseln sein, ein Array oder eine bloße Zahl, und keine dieser Formen bringt einen Namen für die Hülle mit. Die Regel lautet deshalb: Besteht das Objekt aus genau einem Schlüssel, wird dieser Schlüssel zum Wurzelelement. Alles andere wird in ein Element namens root gepackt.

Eine Ausnahme lohnt sich zu kennen, weil sie ausgerechnet die häufigste Form trifft: Hält der einzige Schlüssel ein Array, würde {"positionen": [1, 2]} das Element positionen zweimal an oberster Stelle schreiben und damit gar kein echtes Wurzelelement ergeben. In diesem Fall wird root um das Array herumgelegt. Wer die JSON-Struktur selbst festlegt, sollte die Nutzdaten deshalb in einen sprechenden einzelnen Schlüssel packen — rechnung, bestellung, meldung — statt sich auf root zu verlassen.

XML kennt keinen eigenen Array-Typ und hat auch nie einen gebraucht: Eine Liste ist dasselbe Element, mehrfach im selben Elternelement hintereinandergeschrieben. Ein Objekt mit drei Positionen wird also zu drei aufeinanderfolgenden Elementen namens positionen, und das ist die Form, mit der jeder XML-Verarbeiter ohnehin rechnet.

Das ist die eine Stelle, an der XML besser zu JSON passt als eine tabellarische Form. Bei einer Umwandlung des gleichen Arrays nach CSV müsste zwischen Extraspalten, verknüpften Zeichenketten und zusätzlichen Zeilen entschieden werden, und jede dieser Lösungen ist irgendwo falsch. In XML ist Wiederholung eingebaut, ohne dass jemand entscheiden muss — eine Rechnung mit acht Positionen wandelt sich ohne weiteres Zutun um.

XML unterscheidet zwei Wege, einen Wert an ein Element zu hängen — ein Attribut in der Klammer oder ein Kindelement —, und viele Schemata bestehen darauf, welcher der beiden es sein muss. JSON kennt nur einen. Die Brücke hier: Ein Schlüssel, der mit @ beginnt, wird als Attribut geschrieben, und ein Schlüssel namens #text liefert den eigenen Text des Elements neben seinen Kindern.

Diese Konvention ist nicht willkürlich gewählt, sondern das, was der XML-Leser dieser Website in die andere Richtung erzeugt. Ein Dokument, das nach JSON umgewandelt, bearbeitet und wieder zurückverwandelt wird, bekommt seine Attribute als Attribute zurück statt als Elemente hochgestuft. Erwartet die Gegenstelle etwa eine Rechnungsnummer als Attribut id und liegt sie im JSON als schlichter Schlüssel vor, ist die Umbenennung zu @id die ganze Korrektur.

JSON-Schlüssel dürfen praktisch jede Zeichenkette sein: mit Leerzeichen, Schrägstrichen, führenden Ziffern. XML-Elementnamen dürfen das nicht. Der Schreiber schreibt in diesem Fall um statt abzubrechen, und zwar nach einer bewusst engen Liste — nur A bis Z, a bis z, 0 bis 9, Unterstrich, Punkt und Bindestrich bleiben erhalten, alles andere wird zu einem Unterstrich, und ein Name, der mit einer Ziffer beginnt, bekommt vorn einen weiteren.

Diese Liste ist enger als die von XML 1.0 selbst, und genau das ist der Punkt, an dem es überrascht: XML-Elementnamen dürfen Umlaute, kyrillische oder griechische Buchstaben enthalten, dieser Schreiber lässt keinen davon durch. Ein Schlüssel namens Prüfnummer wird zu Pr_fnummer, straße zu stra_e — die Datei bleibt wohlgeformt, aber die Namen sind nicht die, die ein deutsches Schema erwartet. Solche Schlüssel vor der Umwandlung umzubenennen, ist die verlässliche Korrektur.

Namensräume, XSD-Schemata, DTDs, Verarbeitungsanweisungen — nichts davon lässt sich aus einer JSON-Datei ableiten, weil nichts davon in einer JSON-Datei ausgedrückt werden kann. Genau deshalb ist XML noch immer das Rückgrat des deutschen Behörden- und Finanzdatenaustauschs, von DATEV-Schnittstellen bis zur elektronischen Rechnung.

In der Praxis heißt das: Das Ergebnis ist wohlgeformt, nicht validiert. Prüft die Gegenstelle gegen ein XSD, ist mit einer Namensraum-Deklaration am Wurzelelement zu rechnen und mitunter mit einer anderen Elementreihenfolge, weil eine XSD-Sequenz reihenfolgeabhängig ist und eine JSON-Objektreihenfolge nicht bedeutungstragend ist. Beides sind kleine, schnelle Korrekturen an der Ausgabe, sobald das Dokument einmal vorliegt.

Kaufmännisches Und-Zeichen, spitze Klammern und doppelte Anführungszeichen in einem Wert werden beim Schreiben maskiert — deshalb beendet eine Artikelbeschreibung mit „Muster & Co. <Sonderposten>" das Dokument nicht vorzeitig. Alles andere, einschließlich Apostrophe und jedes nicht-lateinische Zeichen, wird unverändert als UTF-8 geschrieben.

Ein JSON-Nullwert wird zu einem leeren Element: Das Tag steht da, ohne Inhalt dazwischen. Das ist eine bewusste Entscheidung und nicht die einzig mögliche — XML kennt für genau diesen Fall auch xsi:nil, und manche Schemata verlangen ausdrücklich diese Variante. Verlangt die Gegenstelle sie, ist der Austausch der leeren Elemente eine einfache Suche-und-Ersetze-Aktion, und es lohnt sich, das vor der ersten echten Übermittlung zu klären statt danach.

Das Dokument wird mit zwei Leerzeichen Einrückung geschrieben, ein Element pro Zeile — das macht es lesbar und einen Vergleich zweier Nachrichten nachvollziehbar. Es beginnt nicht mit der Zeile <?xml version="1.0"?>. XML 1.0 macht diese Deklaration ausdrücklich freiwillig und legt UTF-8 als Voreinstellung fest, sodass die Datei auch ohne sie wohlgeformt ist.

Manche ältere Schnittstellen sehen das anders und scheitern mit einer wenig hilfreichen Meldung, wenn die Zeile fehlt. Sie ist eine Zeile am Anfang, schnell ergänzt — und gut zu wissen, bevor eine erste Testübermittlung mit „ungültige Datei" scheitert, ohne zu verraten, welche von zwanzig möglichen Ursachen gemeint ist.

Jeder Wert wird von einem öffnenden und einem schließenden Tag umschlossen, sodass der Feldname zweimal pro Datensatz auftaucht statt einmal. Bei vielen kurzen Werten mit langen Feldnamen kann das Dokument zwei- bis dreimal so groß werden wie das JSON, aus dem es entstand, und die Einrückung kommt noch dazu.

Das ist ein echter Kostenfaktor bei einer Warteschlange mit Größenlimit und keiner bei einer Dateiübertragung, wo die meisten dieser Lieferungen ohnehin landen. Wo die Größe wirklich stört, ist Komprimierung die Antwort und nicht Umbau: XML ist hochgradig repetitiver Text und lässt sich mit gzip sehr weit zusammendrücken, und die meisten größenbeschränkten Schnittstellen akzeptieren eine komprimierte Übermittlung.

Zwei Prüfungen, in dieser Reihenfolge. Zuerst Wohlgeformtheit: Jeder XML-Editor, jeder Browser und jeder Parser auf der Kommandozeile sagt in einer Sekunde, ob das Dokument sich parsen lässt, und eine Umwandlung, die etwas Unparsbares erzeugt hat, sollte vor allem anderen auffallen. Das sollte hier immer bestehen.

Die Prüfung gegen das Schema kommt danach, und beim ersten Versuch ist mit Fehlern zu rechnen. Die Meldungen sind aufschlussreich — ein fehlender Namensraum, ein Element in falscher Reihenfolge, eine geforderte Hülle, für die das JSON keinen Grund hatte — und jede davon ist eine kleine Korrektur im JSON oder in der Ausgabe. Einmal durchgeführt, entsteht daraus eine Vorlage, in die jede weitere Meldung passt.

Die Umwandlung ist JavaScript in diesem Tab: Der Browser liest das JSON, ein kleiner Schreiber erzeugt das XML, und keine Anfrage trägt das Dokument irgendwohin. Es gibt keine Registrierung, keine Warteschlange und kein Tageskontingent, und die kostenlose Nutzung erlaubt bis zu 100 MB.

Für diese Zielgruppe ist das oft der entscheidende Punkt und keine Nebensächlichkeit. Was hier zu XML werden muss, sind Zahlungen, Meldungen, Rechnungen und mitunter personenbezogene Daten — genau die Kategorien, bei denen das Einfügen in einen unbekannten Webdienst ein meldepflichtiger Vorfall wäre. Hier wird nichts gesendet, also gibt es nichts zu melden.