XML in JSON umwandeln

Ein großer Teil der deutschen Verwaltungs-Schnittstellen kommuniziert bis heute über SOAP und XML nach den XÖV-Standards — XJustiz, XPersonenstand und verwandte Formate —, und auch das ELSTER-Verfahren der Finanzverwaltung stammt technisch aus dieser Generation. Wer eine eigene Anwendung dagegen schreibt, ein internes Tool, eine Schnittstelle zu einem Fachverfahren, bekommt Antworten in genau diesem XML zurück und muss sie im eigenen Code lesen.

Moderne Werkzeuge und Frontends erwarten dagegen JSON. Diese Seite übersetzt zwischen beiden Welten nach einer festen, nachvollziehbaren Regel — nicht durch Raten, sondern durch dieselbe mechanische Umwandlung bei jeder Datei.

XML trägt Information an drei Stellen — Elementnamen, Attribute und Text —, JSON kennt nur Schlüssel und Werte, also braucht die Abbildung eine Konvention. Jedes Element wird zu einem Schlüssel, dessen Wert ein Objekt seiner Kindelemente ist, jedes Attribut wird zu einem Schlüssel auf demselben Objekt mit vorangestelltem @, und der eigene Text eines Elements, sofern es daneben Kinder oder Attribute trägt, landet unter dem Schlüssel #text.

Ein Element ohne Attribute und ohne Kinder wird dagegen einfach zu einer Zeichenkette, ohne umgebendes Objekt. Diese Unregelmäßigkeit lässt sich nicht auflösen und sollte früh verinnerlicht werden — derselbe Pfad im Dokument liefert je nach Fall mal eine Zeichenkette, mal ein Objekt, abhängig davon, ob das Quellelement zufällig ein Attribut trug.

Das ist der teuerste Punkt beim Verarbeiten umgewandelter XML-Antworten. Ein XML-Dokument sagt nirgends, welche Elemente sich wiederholen können — das steht nur in einem Schema, und der Parser liest keins. Eine Antwort mit einem einzelnen Datensatz-Element erzeugt also ein Objekt, eine mit zwei erzeugt ein Array von Objekten.

Code, der gegen eine vollständige Antwortliste geschrieben wurde, bricht deshalb genau an dem Tag, an dem nur ein Datensatz zurückkommt, und Code für eine Einzelantwort bricht, sobald ausnahmsweise zwei kommen. Es gibt hier keine Einstellung, die das behebt, weil dafür das Schema bekannt sein müsste. Der Konsument sollte jede mögliche Liste als Erstes in ein Array zwingen, bevor irgendeine andere Logik darauf zugreift.

Eine SOAP-Hülle kommt mit ihren Präfixen unverändert an: soap:Envelope wird zu einem Schlüssel, der wörtlich soap:Envelope heißt, und die Namensraum-Deklaration erscheint als Attribut wie @xmlns:soap. Nichts davon wird aufgelöst oder entfernt.

Das ist getreu und zerbrechlich zugleich, weil ein Präfix willkürlich ist. Ein Dienst, der in der einen Woche soapenv:Envelope schreibt und in der nächsten soap:Envelope, hat zwei gleichwertige Dokumente erzeugt, aber zwei unterschiedliche JSON-Strukturen. Wer den Konsumenten selbst schreibt, sollte auf den lokalen Namen nach dem Doppelpunkt prüfen und niemals ein Präfix fest verdrahten, das man nicht selbst festgelegt hat.

Öffnet ein Dokument mit einer Versions- und Kodierungsangabe, entsteht ein oberster Schlüssel namens ?xml mit diesen Werten, direkt neben dem Schlüssel für das Wurzelelement. Das gehört nicht zum eigentlichen Inhalt und steht trotzdem in der JSON-Datei.

Der richtige Umgang damit ist, ihn zu ignorieren oder zu löschen — keinesfalls sollte Code davon ausgehen, dass der erste Schlüssel des Objekts automatisch das Wurzelelement ist. Genau das schlägt bei jedem Dokument fehl, das eine Deklaration trägt, und das sind die meisten.

Zahlenartig aussehende Werte werden zu JSON-Zahlen, in Attributen wie in Elementtext gleichermaßen. Ein Attribut mit dem Wert 1.0 wird zu 1, eine Kennung mit führenden Nullen wie 007 wird zu 7.

Das ist bei Zählwerten praktisch und bei allem, was als reine Zeichenkette gemeint war, ein Problem: Aktenzeichen, Vorgangsnummern und Steueridentifikationsmerkmale können auf diese Weise ihre führenden Nullen verlieren. Ein Wert, der zu groß für eine sichere JSON-Zahl ist, bleibt allerdings als Zeichenkette erhalten und wird nicht gerundet — das ist die eine Stelle, an der die Umwandlung von sich aus vorsichtig ist.

Kommentare fallen beim Einlesen restlos weg. CDATA-Abschnitte werden dagegen ausgepackt: Der Inhalt wird zu einer gewöhnlichen Zeichenkette, sodass ein HTML-Fragment, das eine Behördenschnittstelle in CDATA einbettet, als Text mit spitzen Klammern ankommt — beim Zurückwandeln nach XML würde daraus wieder Text und keine CDATA-Sektion.

Gemischter Inhalt ist der Fall ohne gute Lösung. Ein Element aus Text, dann einem Kindelement, dann weiterem Text behält das Kind unter seinem eigenen Schlüssel und fügt die beiden Textstücke zu einem einzigen #text-Wert zusammen, ohne Markierung, wo das Kind ursprünglich stand. Jedes Dokument, in dem Fließtext und Markup ineinandergreifen, verliert an dieser Stelle seine Reihenfolge, und JSON ist für diesen Fall schlicht das falsche Ziel.

Zusammengesetzt liest sich eine SOAP-Antwort als verschachtelte Schlüssel: der Envelope-Schlüssel, darin der Body-Schlüssel, darin die Operation, darin die eigentlichen Nutzdaten. Jede Ebene behält ihr Präfix, und bis die interessanten Daten auftauchen, liegen bereits drei oder vier Objektebenen dazwischen — genauso ausführlich wie das XML, aber leichter aus Code heraus zu durchlaufen.

Eine Fehlerantwort sollte als Erstes getestet werden. SOAP-Fehler nutzen eine andere Elementstruktur als eine erfolgreiche Antwort, sodass die JSON-Struktur eines Fehlers nichts mit der eines Ergebnisses gemein hat, und ein Client, der nur den Erfolgsfall kennt, liest von einem nicht mehr existierenden Pfad undefined. Am besten eine echte Fehlerantwort einmal umwandeln und den Fehlerzweig genau darauf schreiben, bevor er gebraucht wird.

Ein selbstschließendes Element und ein Element mit leerem Inhalt werden beide zu einer leeren Zeichenkette. XML unterscheidet zwischen beiden ebenfalls nicht, insofern geht dabei nichts verloren — nur dass JSON eigentlich null kennt und es hier nicht verwendet wird: Ein leeres Element wird zu "" und nicht zu null.

Was tatsächlich verschwindet, ist der Unterschied zwischen einem Feld, das im Dokument gar nicht vorkam, und einem, das vorkam und explizit leer war, sobald der eigene Code einen Standardwert einsetzt. Beide wirken danach gleich falsch. Wo dieser Unterschied wichtig ist — ein Feld, das bewusst geleert wurde, gegenüber einem, das nie gesetzt war — hilft nur, auf das Vorhandensein des Schlüssels zu prüfen statt auf seinen Wert.

Die Ausgabe ist mit zwei Leerzeichen eingerückt, lässt sich also gut in einem Code-Review lesen und direkt als Testfixture einfügen. Genau dafür lohnt sie sich am meisten: eine echte Antwort einmal umzuwandeln und ins Repository aufzunehmen, gibt dem eigenen Code etwas Ehrliches zum Testen, samt aller oben beschriebenen Eigenheiten.

Drei Gewohnheiten decken fast jedes Problem dieser Seite ab. Alles, was sich wiederholen kann, in ein Array normalisieren. Kennungen als Zeichenketten vergleichen, und sie an der Systemgrenze zurück in Zeichenketten wandeln, falls der Parser sie zu Zahlen gemacht hat. Namensraum-Schlüssel am lokalen Namensteil erkennen, nicht am vollständigen Präfix. Mit diesen drei Regeln ist die Umwandlung verlässlich, und alles andere daran ist vorhersehbar.