NDJSON in XML umwandeln

Deutsche Behörden tauschen Daten häufig über die XÖV-Familie standardisierter XML-Formate aus — etwa für das Meldewesen oder die Justiz —, und ein zeilenweiser Export aus einem modernen System muss vor der Übergabe erst in genau diese Form gebracht werden. Diese Umwandlung erledigt den ersten, mechanischen Teil davon: aus jeder Zeile wird ein Element in einem einzigen Dokument.

Was danach noch bleibt, ist meist eine Frage der Feinabstimmung — der richtige Elementname, ein Namensraum, die Reihenfolge, die ein Schema verlangt. Diese Seite erklärt, was die Umwandlung selbst liefert und was jemand von Hand nachtragen muss, bevor die Datei tatsächlich zur Schnittstelle passt.

Die beiden Formate stehen an entgegengesetzten Enden derselben Frage. NDJSON ist so gebaut, dass keine Zeile von einer anderen abhängt — man kann die Datei an beliebiger Stelle teilen, nach einem Abbruch fortsetzen, verarbeiten, ohne sie ganz zu halten. Ein XML-Dokument ist das Gegenteil: Es ist erst gültig, wenn das schließende Wurzelelement da ist, also ist die ganze Datei von der ersten bis zur letzten Zeile eine Einheit.

Genau darauf sollte man sich einstellen, nicht auf die Elementnamen. Ein Export eines großen Bestands ergibt ein einzelnes Dokument, das als Ganzes übertragen, geparst und angenommen werden muss — ein Fehler an irgendeiner Stelle scheitert am gesamten Dokument. Wo die Gegenstelle eine Nachrichtengrößengrenze oder eine Wiederholungslogik hat, macht das Teilen der Quelldatei in Stapel vor der Umwandlung den Unterschied zwischen einer Zustellung, die nach einem Fehler weitermacht, und einer, die von vorn beginnt.

Die Form ist festgelegt, weil die Eingabeform es ist. Eine zeilenweise Datei ist immer eine Liste, und eine Liste hat keinen eigenen Namen — deshalb entsteht ein Wurzelelement mit einem item-Element pro Datensatz darunter. Jedes Feld wird zu einem Kindelement, benannt nach seinem Schlüssel, und ein verschachteltes Objekt ergibt darunter weitere Elemente.

Es gibt keine Option, diese beiden Namen während der Umwandlung selbst festzulegen, und es gäbe für den Konverter auch keinen sinnvollen Weg, sie zu erraten — nichts in einer NDJSON-Datei sagt, ob die Datensätze Bestellungen, Meldungen oder Messwerte sind. Die Ausgabe ist bewusst das schlichteste korrekte Dokument, was die anschließende Umbenennung zu einer vorhersehbaren Suchen-und-Ersetzen-Aufgabe macht statt zu einer Entwirrung.

So gut wie jede XML-Schnittstelle benennt ihr Datensatzelement in einem eigenen Schema — ein Meldungen-Dokument mit Meldung-Elementen, ein Vorgänge-Dokument mit Vorgang-Elementen. Die beiden generischen Namen sind also Platzhalter, und sie zu ersetzen ist eine Sache von zwei Minuten in einem Editor: einmal root an beiden Enden, item an jeder Datensatzgrenze.

Das lohnt sich vor der ersten Zustellung, nicht erst nach einer Ablehnung. Ein Intake, das gegen ein Schema prüft, weist das ganze Dokument wegen des Elementnamens zurück und meldet das häufig nicht besonders deutlich. Bei regelmäßigen Lieferungen gehört diese Umbenennung ins Skript, das die Datei verschickt, nicht in die Erinnerung einer einzelnen Person.

Eine Liste in XML war schon immer dasselbe Tag mehrfach hintereinander, deshalb ergibt ein Datensatz mit drei tags-Werten drei nebeneinanderstehende tags-Elemente. Keine Nummerierung, keine Verkettung, keine Entscheidung, die die Umwandlung für einen trifft — die Struktur kommt vollständig an.

Das ist der stärkste Grund, für dieselbe Datei XML den tabellarischen Zielen vorzuziehen. Eine Umwandlung derselben Datensätze in CSV zwingt zu einer Wahl zwischen nummerierten Spalten, einer zusammengefügten Zeichenkette oder zusätzlichen Zeilen, und jede dieser Lösungen verliert etwas. Eine Bestellung mit fünf Positionen oder ein Ereignis mit einer Liste angewendeter Regeln kommt in XML ohne einen einzigen Kompromiss an.

JSON-Schlüssel dürfen fast alles sein — Leerzeichen, Schrägstriche, eine führende Ziffer. XML-Elementnamen dürfen das nicht. Der Schreiber scheitert daran nicht, sondern schreibt um: verbotene Zeichen werden zu Unterstrichen, und ein mit einer Ziffer beginnender Name bekommt einen Unterstrich davor.

Maschinell erzeugte Exporte treffen das häufiger als von Hand geschriebene Dateien. Alles, was nach einem Datum, einer Kennzahl oder einem Kopfzeilenfeld benannt ist, erzeugt eher umgeschriebene Namen, und das Umschreiben geschieht ohne Meldung. Hat die Gegenstelle ein Schema, scheitern diese Elemente an einem Namen, den niemand wiedererkennt — es lohnt sich, die Ausgabe vor der ersten Lieferung auf Unterstriche zu durchsuchen.

Der Abgleich, den die tabellarischen Umwandlungen vornehmen, findet hier nicht statt und wird auch nicht gebraucht. Jedes item-Element trägt genau die Felder, die seine Zeile hatte — eine Datei mit gemischten Ereignistypen ergibt also item-Elemente unterschiedlicher Form innerhalb desselben Dokuments, was gültiges XML, aber gegen ein striktes Schema meist ungültig ist.

Ein Schema mit einer festen Elementfolge weist den ersten Datensatz zurück, dem ein Element fehlt. In diesem Fall entweder die Quelle vor der Umwandlung auf einen Datensatztyp filtern oder die fehlenden Elemente leer ergänzen — wobei ein leeres Element und ein als nillable deklariertes Element für einen strengen Validator zwei verschiedene Dinge sind. Welche der beiden Formen die Gegenstelle erwartet, steht in deren Dokumentation und ist besser einmal geklärt als nach jedem zweiten Ablehnungslauf neu erraten.

Kaufmännisches Und, spitze Klammern und doppelte Anführungszeichen in einem Wert werden maskiert, damit eine Produktbeschreibung oder eine Protokollzeile mit zufälligem Markup das Dokument nicht vorzeitig beendet. Alles Übrige, einschließlich Umlauten und nicht-lateinischer Schrift, wird als UTF-8 durchgereicht.

Ein JSON-Nullwert wird zu einem leeren Element: Das Tag ist vorhanden, dazwischen steht nichts. Manche Schemata verlangen dafür xsi:nil, andere erwarten das Element gar nicht erst — unterscheidet die Gegenstelle diese Fälle, ist das eine nachgelagerte, skriptgesteuerte Anpassung der Ausgabe, weil die Quelle nur eine einzige Art kennt, „nichts" auszudrücken.

Jeder Feldname erscheint zweimal pro Datensatz — einmal im öffnenden, einmal im schließenden Tag —, wo NDJSON ihn einmal schreibt. Zusammen mit der Einrückung landet ein Dokument aus kurzen Werten und langen Feldnamen leicht bei der zwei- bis dreifachen Größe der Ursprungsdatei.

Bei einer SFTP-Übergabe spielt das keine Rolle. Bei einer Nachrichtenwarteschlange mit Größenlimit entscheidet es, wie viele Datensätze pro Stapel passen. Die übliche Antwort ist Kompression statt Umbau: XML dieser Art wiederholt sich stark und lässt sich sehr gut komprimieren, und die meisten größenbegrenzten Schnittstellen akzeptieren eine komprimierte Übergabe.

Bis zu hundert Dateien lassen sich gleichzeitig ablegen, jede wird zu einem eigenen XML-Dokument. Bei regelmäßigen Lieferungen an dieselbe Schnittstelle — etwa ein täglicher Export, der in mehrere Stapel geteilt wurde, weil die Gegenstelle eine Größengrenze setzt — lässt sich so die ganze Serie in einem Arbeitsschritt umwandeln.

Weil keine Serverkapazität verbraucht wird, gibt es keine Warteschlange dazwischen; die praktische Grenze ist der Arbeitsspeicher des eigenen Geräts, und bei mehreren großen Dokumenten gleichzeitig macht sich das eher bemerkbar als bei einer einzelnen Datei.

Die Umwandlung läuft im Browser-Tab: Die Datei wird zeilenweise gelesen, das Dokument von einem kleinen Schreibmodul in der Seite zusammengesetzt. Nichts wird hochgeladen, es gibt kein Konto und keine Warteschlange, und die freie Grenze liegt bei 100 MB — der eigentliche Deckel ist der Arbeitsspeicher des Geräts, weil das Dokument als Ganzes im Speicher entsteht.

Die Daten, die auf diesem Weg unterwegs sind, sind selten belanglos. Lieferungen an eine Behörde, eine Bank oder einen Vertragspartner sind genau die Dateien mit einer Vertraulichkeitsklausel, und eine Umwandlung über einen unbekannten Webdienst wäre eine zweite Offenlegung, der niemand zugestimmt hat. Hier gibt es nichts offenzulegen — der Netzwerk-Tab während einer Umwandlung zeigt das unmittelbar.