JSON-Ausgabeformate verstehen: Array, Keyed, Nested und JSON Lines (NDJSON)

Eine CSV in JSON umzuwandeln klingt nach einer einzigen, eindeutigen Operation. Tatsächlich gibt es aber mehrere gleichwertige JSON-Darstellungen derselben Tabelle, und welche die richtige ist, hängt vollständig davon ab, was am anderen Ende damit passiert. Wer die Daten in eine Web-Anwendung lädt, braucht ein anderes Format als jemand, der sie nach MongoDB importiert oder als Log-Strom verarbeitet. Dieser Artikel ordnet die vier wichtigsten Ausgabeformate ein: das klassische Array, das Keyed-Objekt, verschachteltes (nested) JSON und JSON Lines, besser bekannt als NDJSON.

Die Ausgangsdaten: eine flache CSV

Damit der Vergleich nachvollziehbar bleibt, nutzen alle folgenden Beispiele dieselbe kleine CSV-Tabelle mit drei Datensätzen. Die erste Zeile ist die Kopfzeile mit den Spaltennamen:

id,name,stadt,aktiv
1,Anna Köhler,Hamburg,true
2,Bjørn Maaß,Kiel,false
3,Cem Yıldız,Lübeck,true

Aus dieser Tabelle entstehen je nach gewähltem Ausgabeformat vier strukturell verschiedene JSON-Dokumente. Inhaltlich sind sie identisch, technisch verhalten sie sich sehr unterschiedlich.

Die vier Formate auf einen Blick

Eine Tabelle als Eingabe, vier mögliche Ausgaben. Das folgende Diagramm zeigt, wie sich dieselbe CSV in die vier Zielformate verzweigt und wofür jedes typischerweise gedacht ist.

Format 1: Das klassische JSON-Array

Das Array ist die häufigste und intuitivste Form. Jede Datenzeile wird zu einem Objekt, alle Objekte werden in eine eckige Klammer eingeschlossen und durch Kommas getrennt. Die Kopfzeile liefert die Schlüsselnamen. Das Ergebnis ist ein einziges, gültiges JSON-Dokument.

[
  { "id": 1, "name": "Anna Köhler", "stadt": "Hamburg", "aktiv": true },
  { "id": 2, "name": "Bjørn Maaß", "stadt": "Kiel", "aktiv": false },
  { "id": 3, "name": "Cem Yıldız", "stadt": "Lübeck", "aktiv": true }
]

Dieses Format passt fast immer, wenn die Daten in eine Web-Anwendung, ein JavaScript-Frontend oder eine API gehen. Es lässt sich mit einem einzigen Aufruf (etwa JSON.parse oder json.loads) komplett einlesen und in eine Liste verwandeln. Der einzige Nachteil: Die gesamte Datei muss am Stück geparst werden, was bei sehr großen Mengen Speicher kostet.

Format 2: Das Keyed-Objekt

Statt einer Liste erzeugt das Keyed-Format ein einziges großes Objekt. Der Wert einer Schlüsselspalte, hier die id, wird zum Schlüssel des jeweiligen Datensatzes. So können Sie später direkt über die ID auf einen Eintrag zugreifen, ohne das ganze Array zu durchsuchen.

{
  "1": { "name": "Anna Köhler", "stadt": "Hamburg", "aktiv": true },
  "2": { "name": "Bjørn Maaß", "stadt": "Kiel", "aktiv": false },
  "3": { "name": "Cem Yıldız", "stadt": "Lübeck", "aktiv": true }
}

Der direkte Zugriff per Schlüssel (daten["2"]) ist der große Vorteil. Die wichtigste Bedingung: Die Schlüsselspalte muss eindeutige Werte enthalten. Tauchen Werte doppelt auf, überschreibt der letzte Datensatz die vorherigen, und Daten gehen verloren. Für Nachschlagetabellen und Konfigurationen ist das Format ideal, für Datensätze ohne eindeutige ID ungeeignet.

Format 3: Verschachteltes (nested) JSON

Die wahre Stärke von JSON liegt in der Verschachtelung, und auch eine flache CSV lässt sich dorthin überführen. Der Trick ist die Punkt-Notation in den Spaltennamen. Eine Spalte adresse.stadt wird beim Konvertieren zu einem Schlüssel stadt innerhalb eines Unterobjekts adresse. Aus dieser CSV:

id,name,adresse.stadt,adresse.plz
1,Anna Köhler,Hamburg,20095

entsteht durch die Punkt-Notation diese verschachtelte Struktur:

{
  "id": 1,
  "name": "Anna Köhler",
  "adresse": {
    "stadt": "Hamburg",
    "plz": "20095"
  }
}

Nested JSON ist genau dann die richtige Wahl, wenn das Zielsystem strukturierte Objekte erwartet, etwa eine API, die einen Kunden samt Adresse als ein zusammenhängendes Objekt verlangt. So lassen sich mehrere Spaltengruppen sauber in logische Untereinheiten gliedern, ohne die flache CSV-Quelle ändern zu müssen.

Format 4: JSON Lines (NDJSON)

JSON Lines, in der Praxis fast immer als NDJSON (Newline Delimited JSON) bezeichnet, bricht bewusst mit der Array-Logik. Hier ist jede Zeile ein eigenständiges, vollständiges JSON-Objekt. Es gibt keine umschließenden eckigen Klammern und keine Kommas zwischen den Objekten, getrennt wird allein durch den Zeilenumbruch:

{"id":1,"name":"Anna Köhler","stadt":"Hamburg","aktiv":true}
{"id":2,"name":"Bjørn Maaß","stadt":"Kiel","aktiv":false}
{"id":3,"name":"Cem Yıldız","stadt":"Lübeck","aktiv":true}

Der entscheidende Vorteil: Ein Programm kann die Datei Zeile für Zeile lesen und verarbeiten, ohne sie komplett in den Speicher zu laden. Genau deshalb ist NDJSON das Standardformat für Datenströme, für Logdateien und für den massenhaften Datenbankimport. Fällt die Verarbeitung in Zeile 900.000 aus, sind die ersten 899.999 Datensätze trotzdem bereits sauber eingelesen, ein abgebrochenes Array wäre dagegen unbrauchbar.

Diese Werkzeuge erwarten oder bevorzugen NDJSON beim Laden von JSON-Daten:

• MongoDB: mongoimport liest standardmäßig ein Objekt pro Zeile, ein Array nur mit --jsonArray.
• Google BigQuery: Lädt JSON ausschließlich im zeilengetrennten Format (newline delimited JSON).
• Amazon Athena und viele Big-Data-Werkzeuge erwarten ebenfalls ein Objekt je Zeile.
• Log-Systeme wie der Elastic Stack verarbeiten Ereignisse zeilenweise als NDJSON.

Direktvergleich: welches Format wofür?

Datentypen: warum sie bei jedem Format zählen

Unabhängig vom gewählten Ausgabeformat stellt sich immer dieselbe Frage: Sollen 42 und true als echte JSON-Zahl und echter Wahrheitswert ausgegeben werden, oder als Zeichenketten? In CSV ist alles Text, JSON unterscheidet dagegen zwischen Zahlen, Wahrheitswerten, null und Strings. Eine automatische Typ-Erkennung wandelt erkennbare Zahlen und true/false in die passenden JSON-Typen um. Das ist meist erwünscht, kann aber stören, etwa bei Postleitzahlen oder Artikelnummern mit führenden Nullen, die als Zahl ihre Null verlieren würden. Ein guter Konverter bietet deshalb eine Option, alle Werte als String zu behalten.

Sehr große Dateien: NDJSON als Speicherspar-Trick

Je größer die Datenmenge, desto klarer spielt NDJSON seine Stärke aus. Ein Array zwingt jeden Leser, das gesamte Dokument im Arbeitsspeicher zu halten, bevor er überhaupt mit der Verarbeitung beginnen kann. Bei mehreren hundert Megabyte kann das einen Browser oder ein Skript in die Knie zwingen. NDJSON erlaubt dagegen das sogenannte Streaming: Zeile lesen, Objekt parsen, verarbeiten, nächste Zeile. Der Speicherbedarf bleibt konstant, egal ob die Datei tausend oder zehn Millionen Zeilen hat. Wer regelmäßig mit großen Exporten arbeitet, sollte NDJSON daher zur Standardwahl machen.

Häufig gestellte Fragen

Quellen und Standards

• jsonlines.org: JSON Lines, Spezifikation des zeilengetrennten Formats
• IETF: RFC 8259, The JavaScript Object Notation (JSON) Data Interchange Format
• IETF: RFC 4180, Common Format and MIME Type for CSV Files
• MongoDB: mongoimport, JSON-Import (Objekt pro Zeile)
• Google Cloud: BigQuery, Laden von newline delimited JSON
• MDN Web Docs: Das JSON-Objekt in JavaScript

Verwandte Artikel