Was ist der Unterschied zwischen JSON Lines und NDJSON?

Beide Namen bezeichnen praktisch dasselbe: Jede Zeile enthält einen gültigen JSON-Wert, die Zeilen sind durch einen Zeilenumbruch getrennt. Die Beschreibungen unter jsonlines.org und im ndjson-spec unterscheiden sich in Details, gebräuchliche Dateiendungen sind .jsonl und .ndjson.

Ist eine JSON-Lines-Datei gültiges JSON?

Als Ganzes nicht. Erst jede einzelne Zeile ist ein gültiges JSON-Dokument. Ein Parser, der ein einzelnes JSON-Dokument erwartet, bricht bei der zweiten Zeile ab. Man liest die Datei deshalb zeilenweise.

Wann nehme ich ein Array statt JSON Lines?

Wenn das Ziel genau ein JSON-Dokument erwartet, etwa die Antwort einer Schnittstelle oder eine Konfigurationsdatei, oder wenn die Datei klein ist und gut lesbar sein soll. JSON Lines lohnt sich bei vielen gleichförmigen Datensätzen und beim zeilenweisen Verarbeiten.

JSON Lines (NDJSON): Format, Nutzen, Umwandlung

Ein klassisches JSON-Array packt alle Datensätze in eckige Klammern. Dafür muss ein Programm die ganze Datei lesen, bevor es den ersten Datensatz sicher kennt, denn erst die schließende Klammer macht das Dokument gültig. JSON Lines dreht das um: Jede Zeile ist ein eigenständiges JSON-Dokument.

So sieht das Format aus

Aus dieser CSV:

PLZ;Ort;Einwohner
01067;Dresden;566222
20095;Hamburg;1910160

wird mit Typerkennung dieses JSON Lines:

{"PLZ":"01067","Ort":"Dresden","Einwohner":566222}
{"PLZ":"20095","Ort":"Hamburg","Einwohner":1910160}

Es gibt kein umschließendes Array und keine Kommas zwischen den Zeilen. Zeilenumbrüche innerhalb der Werte stehen als \n im Text, damit eine Zeile immer ein Datensatz ist. Die Dateien sind UTF-8-codiert.

Wofür das Format taugt

Große Dateien: Programme lesen und verarbeiten Zeile für Zeile, ohne die ganze Datei im Speicher zu halten.
Anhängen: Neue Datensätze lassen sich ans Dateiende schreiben, ohne die Datei umzubauen. Deshalb sind Logs oft zeilenweise JSON.
Importe: mongoimport erwartet standardmäßig ein Dokument pro Zeile und liest ein Array nur mit der Option --jsonArray. Auch andere Datenwerkzeuge, etwa Ladejobs in BigQuery, arbeiten mit zeilengetrenntem JSON. Prüfen Sie im Einzelfall die Dokumentation des Ziels, denn manche Schnittstellen verlangen zusätzliche Zeilen, so die Bulk-API von Elasticsearch mit Aktionszeilen.

Wann ein Array besser ist

Schnittstellen und Konfigurationsdateien erwarten meist genau ein JSON-Dokument. Für kleine Datenmengen, die ein Mensch lesen soll, ist ein eingerücktes Array übersichtlicher. Außerdem kennen Editoren und viele Werkzeuge JSON Lines weniger gut als normales JSON.

Umwandlung aus CSV

Wählen Sie im Konverter das Ausgabeformat „JSON Lines (NDJSON)“. Die Optionen zu Trennzeichen, Typerkennung und leeren Feldern gelten wie gewohnt. Der Download hat die Endung .jsonl. Ohne Kopfzeile besteht jede Zeile aus einer Liste statt aus einem Objekt. Die Einrückung entfällt, denn jeder Datensatz steht in einer Zeile.

Verschachtelte Objekte sind möglich: Mit der Option für Punkt-Pfade wird aus der Spalte adresse.ort ein Objekt adresse mit dem Feld ort, und der Datensatz bleibt trotzdem eine Zeile.

Selbst erzeugen

In JavaScript genügt zeilen.map((z) => JSON.stringify(z)).join("\n"). JSON.stringify ohne Einrückung erzeugt keine Zeilenumbrüche außerhalb von Textwerten. In Python schreibt json.dumps(satz, ensure_ascii=False) pro Zeile einen Datensatz.

Worauf es ankommt

JSON Lines eignet sich für viele gleichförmige Datensätze, die zeilenweise verarbeitet oder angehängt werden. Für einzelne Dokumente und kleine Datenmengen bleibt das Array die bessere Wahl. Beide Formate erzeugt der Konverter aus derselben CSV, wie die Anleitung zeigt.