NDJSON in JSON umwandeln

Wer in einem Unternehmen für eine Auskunft nach Artikel 15 DSGVO zuständig ist, bekommt aus dem Ereignisprotokoll eines Systems — einer Kafka-Pipeline, einem Logging-Dienst, einer internen Anwendung — oft eine Datei mit einem JSON-Objekt pro Zeile zurück, weil genau dieses Format sich am einfachsten aus einem laufenden System exportieren lässt. Für die weitere Bearbeitung, etwa eine Prüfung durch die Rechtsabteilung oder eine Aufbereitung für die betroffene Person, verlangt das nächste Werkzeug in der Kette aber ein einziges gültiges JSON-Dokument.

Das ist keine Formsache. Ein JSON-Schema-Prüfer, ein internes Auskunftstool oder ein einfacher Import in ein Tabellenprogramm über eine JSON-Schnittstelle weist eine Datei mit mehreren Zeilen als fehlerhaft zurück, obwohl jede einzelne Zeile für sich genommen korrektes JSON ist. Das Problem liegt nicht am Inhalt, sondern an der Form drumherum.

Ein JSON-Dokument ist per Definition genau ein Wert. Eine NDJSON-Datei ist eine Folge von Werten mit Zeilenumbrüchen dazwischen, und das bleibt so, egal wie viel guter Wille beim Lesen aufgebracht wird — ein Parser liest das erste Objekt, stößt auf die öffnende Klammer des zweiten und bricht mit einem Fehler über ein unerwartetes Zeichen ab. Das ist kein Fehler im Parser, sondern der Grund, warum diese Umwandlung überhaupt gebraucht wird.

In der Praxis zeigt sich das an unerwarteten Stellen: Ein Schema-Prüfer weist die Datei ab, ein Importformular meldet ungültige Eingabe, ein internes Skript bricht bereits in der zweiten Zeile ab, obwohl diese Zeile für sich betrachtet einwandfrei ist. Die Lösung ist in jedem dieser Fälle dieselbe eine Zeile Struktur: eckige Klammern um das Ganze, Kommas zwischen den Datensätzen.

Jede Zeile wird zu einem Element eines Arrays auf oberster Ebene, in der ursprünglichen Reihenfolge — auch dann, wenn die Quelle nur eine einzige Zeile enthält. Eine Datei mit einem Eintrag ergibt ein Array mit einem Element, nicht ein einzelnes Objekt ohne Umhüllung, und diese Vorhersehbarkeit ist genau das, was ein nachgelagertes Skript ohne vorherige Prüfung verarbeiten kann.

Die meisten internen Auskunftstools erwarten die Datensätze allerdings nicht als bloßes Array, sondern unter einem benannten Schlüssel, etwa als Teil eines Objekts mit einer Fallnummer daneben. Diese Umhüllung fügt die Umwandlung nicht selbst hinzu, weil ein erfundener Schlüsselname eine Vermutung über eine Schnittstelle wäre, die von hier aus nicht zu sehen ist — das bleibt ein bewusster, separater Schritt.

Das ist bei diesem Ziel der entscheidende Unterschied zu den benachbarten Umwandlungen derselben Ausgangsdatei. Wird dieselbe NDJSON-Datei stattdessen zu CSV, XLSX oder Parquet umgewandelt, werden verschachtelte Objekte in Spalten mit Punktnotation aufgelöst und die Datensätze gegen eine gemeinsame Spaltenliste abgeglichen. Hier passiert nichts dergleichen: Ein verschachteltes Feld mit mehreren Ebenen bleibt genauso verschachtelt in der JSON-Ausgabe stehen.

Auch die Typen bleiben, wie sie waren. Eine Zahl bleibt eine Zahl, ein Wahrheitswert bleibt einer, null bleibt null, und eine numerische Zeichenkette bleibt in Anführungszeichen — weil nichts geraten werden muss, wenn die Quelle bereits JSON ist und das Ziel ebenfalls. Auch die Reihenfolge der Felder innerhalb jedes Datensatzes bleibt erhalten, was das Ergebnis gegen einen früheren Export derselben Daten vergleichbar macht.

Lässt sich eine einzige Zeile nicht als JSON lesen, wird nichts geschrieben. Die Meldung nennt die Zeilennummer, etwa dass Zeile 3 kein gültiges JSON enthält. Es entsteht kein unvollständiges Dokument, und kein Datensatz wird stillschweigend übersprungen.

Bei einem Auskunftsprotokoll ist das mehr wert als bei einer gewöhnlichen Tabelle. Eine abgeschnittene letzte Zeile — meist durch einen mitten im Schreiben abgebrochenen Prozess entstanden — würde sonst ein Dokument ergeben, das sich anstandslos einlesen und validieren lässt und dabei eine unbekannte Zahl von Datensätzen einfach nicht enthält. Die genannte Zeile lässt sich gezielt reparieren oder entfernen, und man weiß danach genau, was fehlt. Leere Zeilen sind dagegen unproblematisch und werden übersprungen, an welcher Stelle der Datei auch immer sie stehen — die genannte Zeilennummer zählt dann die verbliebenen, nicht leeren Zeilen.

Die Ausgabe wird mit zwei Leerzeichen pro Verschachtelungsebene eingerückt, sodass ein Datensatz, der in der Quelle eine einzige dichte Zeile war, hier eine Zeile pro Feld belegt. Bei einer flachen Datei mit einem Dutzend Feldern wächst die Zeilenzahl entsprechend, und mit ihr die Bytezahl durch die Einrückung selbst.

Das betrifft keine Daten, sondern nur die Darstellung, und es fällt bei einer Übertragung praktisch nicht ins Gewicht. Geht das Ergebnis in ein Upload-Feld mit Größenbegrenzung, liefert jq -c . die kompakte Form ohne Einrückung — und es lohnt sich, vorher zu prüfen, ob die Zielstelle nicht ohnehin auch NDJSON direkt entgegennimmt.

Beide Hälften dieser Umwandlung sind Operationen auf dem ganzen Wert: Die Zeilen werden vollständig in ein Array eingelesen, bevor irgendetwas geschrieben wird, und das Array wird in einem Zug serialisiert. Nichts wird gestreamt, und das kann bei dieser Zielform auch nicht anders sein — ein Array ist erst fertig, wenn sein letztes Element feststeht.

Die freie Grenze liegt bei 100 Megabyte je Datei, und die praktische Grenze ist der Arbeitsspeicher des Browser-Tabs. Für ein Exportprotokoll aus einem Auskunftsverfahren ist das in aller Regel mehr als genug; bei sehr großen Beständen lässt sich eine NDJSON-Datei gefahrlos an jeder Zeilengrenze aufteilen, etwa mit split -l, und jeder Teil wandelt für sich sauber um.

Wird das Ergebnis später wieder in NDJSON zurückverwandelt, kommt genau das heraus, was am Anfang stand. Ein Array auf oberster Ebene wird zeilenweise geschrieben, ein Element pro Zeile, mit denselben Feldern in derselben Reihenfolge — es gibt auf keiner der beiden Seiten einen Schritt, der etwas verändert.

Das macht das Paar zu einem brauchbaren Zwischenschritt statt zu einer endgültigen Migration: zu JSON umwandeln, den Schema-Prüfer laufen lassen, gemeldete Probleme in einem richtigen JSON-Editor mit Klammerprüfung korrigieren, zurückwandeln, und das korrigierte Protokoll an das System übergeben, das ursprünglich Zeilen erwartet hat.

Nimmt das Zielsystem zeilenweises JSON ohnehin entgegen, sollte man es dabei belassen. Massenimporte in Elasticsearch, viele Log-Pipelines und mehrere Data-Warehouse-Werkzeuge verlangen NDJSON gerade deshalb, weil ein einziges großes Array den Empfänger zwingt, alles auf einmal im Speicher zu halten. Eine Umwandlung aus reiner Vorliebe statt aus Notwendigkeit macht die Datei nur größer und die Verarbeitung langsamer.

Die Originaldatei aufzuheben lohnt sich in jedem Fall. Das Array hat außer der Eigenschaft, ein einziger Wert zu sein, keinen Vorteil gegenüber den einzelnen Zeilen, während die Zeilen mehrere Vorteile behalten, die das Array nicht hat: Sie lassen sich anhängen, ohne die Datei neu zu schreiben, mit jq filtern, ohne alles einzulesen, und ein beschädigtes Byte beschädigt nur einen Datensatz statt des gesamten Dokuments.

Die Umwandlung ist einfaches JavaScript in der Seite. Es wird keine Erweiterung nachgeladen, keine Anfrage überträgt die Datei, es gibt kein Konto und kein Tageslimit, und der Netzwerk-Tab während der Umwandlung ist die Kontrolle, nicht dieser Satz.

Bei Auskunftsprotokollen, internen Log-Exporten oder Kundendaten auf dem Weg in eine Prüfung ist das kein nebensächliches Detail, sondern häufig genau die Voraussetzung, unter der die Umwandlung überhaupt zulässig ist — vieles davon ist genau das Material, das ein Unternehmen an keinen Webdienst weitergeben darf. Es gibt nichts zu verbieten, wenn nichts gesendet wird.