Von Jerry Fan

NDJSON: Der vollständige Leitfaden zu Newline Delimited JSON

Ein umfassender Leitfaden zu Newline Delimited JSON (NDJSON): Lernen Sie die Spezifikation und den MIME-Typ kennen, lesen und schreiben Sie NDJSON mit Python, Node.js und auf der Kommandozeile und setzen Sie das Format in HTTP-Streaming-APIs ein. Außerdem erfahren Sie, wie NDJSON und JSONL zusammenhängen.

Was ist NDJSON?

NDJSON steht für Newline Delimited JSON. Bei diesem textbasierten Datenformat enthält jede Zeile genau einen gültigen JSON-Wert. Die Werte sind durch ein Zeilenumbruchzeichen (\n) voneinander getrennt. Das Format wurde entwickelt, um große Datenmengen zu streamen und zu verarbeiten, ohne die gesamte Datei in den Arbeitsspeicher zu laden. Während eine herkömmliche JSON-Datei alle Daten in einem einzigen Array oder Objekt zusammenfasst, lassen sich Datensätze mit NDJSON einzeln lesen, schreiben und verarbeiten.

Die NDJSON-Spezifikation ist auf github.com/ndjson/ndjson-spec veröffentlicht. Sie formalisiert ein Muster, das sich beim Log-Shipping, in Datenpipelines und in HTTP-Streaming-APIs bereits etabliert hatte. Jede Zeile ist in sich abgeschlossen: Enthält eine Zeile ungültiges JSON, lassen sich die anderen Zeilen weiterhin parsen. Dadurch ist NDJSON fehlertolerant und eignet sich gut für Append-only-Workflows, bei denen Daten nur angehängt werden, etwa für Anwendungslogs, Event-Streams und inkrementelle Datenexporte.

NDJSON-Beispiel (3 Datensätze)
{"id":1,"event":"page_view","url":"/home"}
{"id":2,"event":"click","url":"/pricing"}
{"id":3,"event":"signup","url":"/register"}

Die NDJSON-Spezifikation

Die offizielle NDJSON-Spezifikation auf github.com/ndjson/ndjson-spec ist bewusst knapp gehalten. Sie legt eine einfache Konvention fest, um mehrere JSON-Werte in einem einzigen Textstream zu serialisieren. Die zentralen Regeln sind überschaubar:

Die Spezifikation verzichtet bewusst auf Header, Metadaten und Schemaangaben im Format selbst. So bleibt NDJSON möglichst einfach und mit den üblichen Unix-Werkzeugen zur Textverarbeitung kompatibel. Jede Zeile darf einen beliebigen gültigen JSON-Wert enthalten. In der Praxis bestehen die meisten NDJSON-Dateien jedoch aus JSON-Objekten mit einheitlichen Schlüsseln.

  • Jede Zeile MUSS genau einen gültigen JSON-Wert enthalten (Objekt, Array, String, Zahl, Boolean oder null).
  • Zeilen werden durch das Zeilenumbruchzeichen '\n' (U+000A) getrennt. Vor '\n' darf ein Wagenrücklaufzeichen '\r' (U+000D) stehen, es ist jedoch nicht erforderlich.
  • Ein abschließender Zeilenumbruch nach dem letzten JSON-Wert ist zulässig, aber nicht erforderlich.
  • JSON-Werte dürfen selbst keine unmaskierten Zeilenumbruchzeichen enthalten.

Dank dieser wenigen Regeln lässt sich NDJSON in jeder Programmiersprache erzeugen, die einen JSON-Serialisierer bietet. Serialisieren Sie jeden Datensatz, hängen Sie einen Zeilenumbruch an und schreiben Sie das Ergebnis in die Ausgabe. Um schließende Klammern, abschließende Kommas oder ein umschließendes Array müssen Sie sich nicht kümmern.

NDJSON vs JSON vs JSONL

NDJSON, JSON und JSONL unterscheiden sich in ihrem Aufbau. Herkömmliches JSON bildet einen einzelnen Wert ab, meist ein Array oder Objekt. JSONL und NDJSON speichern dagegen jeweils einen JSON-Wert pro Zeile und sind funktional identisch. Die folgende Tabelle zeigt die wichtigsten Unterschiede zwischen den drei Formaten.

EigenschaftJSONJSONLNDJSON
Vollständiger NameJavaScript Object NotationJSON LinesNewline Delimited JSON
Dateiendung.json.jsonl.ndjson
MIME-Typapplication/jsonapplication/jsonl (inoffiziell)application/x-ndjson
SpezifikationRFC 8259 (IETF-Standard)jsonlines.org (Community)github.com/ndjson/ndjson-spec (Community)
ZeilentrennerNicht zutreffend (einzelner Wert)\n (Zeilenumbruch)\n (Zeilenumbruch)
Abschließender ZeilenumbruchN/AEmpfohlenOptional
Für Streaming geeignetNein (gesamtes Dokument muss geparst werden)Ja (zeilenweise)Ja (zeilenweise)

NDJSON-MIME-Typ: application/x-ndjson

Der registrierte MIME-Typ für NDJSON lautet application/x-ndjson. Er gibt in HTTP-Headern an, dass der Antwortbody JSON-Daten enthält, die durch Zeilenumbrüche getrennt sind. Viele Streaming-APIs, darunter die GitHub-API, die Docker-Registry-API und die Elasticsearch-Bulk-API, verwenden diesen MIME-Typ für NDJSON-Antworten.

HTTP-Header Content-Type
Content-Type: application/x-ndjson


# Example: curl a streaming API
curl -H "Accept: application/x-ndjson" https://api.example.com/events/stream


# Example: Express.js response
res.setHeader('Content-Type', 'application/x-ndjson');
res.write(JSON.stringify(record) + '\n');

Einige APIs akzeptieren auch application/json-seq (RFC 7464) oder text/plain als Alternative. Am weitesten verbreitet ist jedoch application/x-ndjson für JSON-Streams mit einem Wert pro Zeile. Wenn Sie eine neue API entwickeln, die JSON-Datensätze streamt, verwenden Sie für größtmögliche Kompatibilität application/x-ndjson.

NDJSON lesen und schreiben

NDJSON lässt sich in jeder Sprache, die JSON unterstützt, unkompliziert verarbeiten. Hier finden Sie praktische Beispiele für Python, Node.js und die Kommandozeile.

Mit dem integrierten json-Modul von Python lässt sich NDJSON einfach verarbeiten: Lesen Sie eine Datei zeilenweise ein, parsen Sie jede Zeile mit json.loads und schreiben Sie die Daten mit json.dumps. Bei großen Dateien bleibt der Speicherbedarf durch die zeilenweise Verarbeitung konstant.

Python: NDJSON lesen und schreiben
import json


# Read NDJSON
records = []
with open('data.ndjson', 'r') as f:
    for line in f:
        line = line.strip()
        if line:
            records.append(json.loads(line))


print(f'Loaded {len(records)} records')


# Write NDJSON
output = [
    {'id': 1, 'event': 'page_view', 'url': '/home'},
    {'id': 2, 'event': 'click', 'url': '/pricing'},
    {'id': 3, 'event': 'signup', 'url': '/register'},
]


with open('output.ndjson', 'w') as f:
    for record in output:
        f.write(json.dumps(record) + '\n')

In Node.js können Sie NDJSON-Dateien mit dem readline-Modul und fs.createReadStream effizient parsen. Der Stream verarbeitet jeweils eine Zeile, sodass der Speicherbedarf unabhängig von der Dateigröße gering bleibt.

Node.js: NDJSON lesen und schreiben
import { createReadStream, writeFileSync } from 'node:fs';
import { createInterface } from 'node:readline';


// Read NDJSON
async function readNdjson(filePath) {
  const records = [];
  const rl = createInterface({
    input: createReadStream(filePath, 'utf-8'),
    crlfDelay: Infinity,
  });
  for await (const line of rl) {
    const trimmed = line.trim();
    if (trimmed) records.push(JSON.parse(trimmed));
  }
  return records;
}


// Write NDJSON
const data = [
  { id: 1, event: 'page_view' },
  { id: 2, event: 'click' },
];
const ndjson = data.map(r => JSON.stringify(r)).join('\n') + '\n';
writeFileSync('output.ndjson', ndjson, 'utf-8');

Das Kommandozeilentool jq unterstützt NDJSON-Eingaben nativ. Mit dem Flag --slurp sammeln Sie alle Datensätze in einem Array. Ohne Flag wird jeder Datensatz einzeln verarbeitet.

Kommandozeile: NDJSON mit jq verarbeiten
# Print each record (jq reads NDJSON by default)
jq '.' data.ndjson


# Filter records where event is "click"
jq 'select(.event == "click")' data.ndjson


# Extract specific fields
jq '{id, url}' data.ndjson


# Count total records
jq -s 'length' data.ndjson


# Convert NDJSON to a JSON array
jq -s '.' data.ndjson > data.json


# Convert a JSON array back to NDJSON
jq -c '.[]' data.json > data.ndjson

NDJSON in HTTP-Streaming-APIs

NDJSON ist der De-facto-Standard für HTTP-Streaming-APIs, die Echtzeitdaten liefern. Sendet ein Server eine NDJSON-Antwort, kann der Client den ersten Datensatz verarbeiten, sobald dieser eintrifft. Er muss also nicht auf die vollständige Antwort warten. Das ist schneller und benötigt weniger Arbeitsspeicher als die Rückgabe eines großen JSON-Arrays.

Zu den bekannten Diensten mit NDJSON-Streaming gehören Docker Registry (Events zu Image-Layern), Elasticsearch (Bulk-Operationen), Apache CouchDB (Changes-Feed) und viele moderne ereignisgesteuerte APIs. Das Muster eignet sich gut für Alternativen zu Server-Sent Events, zum Mitlesen von Logs in Echtzeit und zum schrittweisen Laden von Daten in Webanwendungen.

NDJSON-Streaming-Server mit Express.js
import express from 'express';


const app = express();


app.get('/api/events/stream', (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');
  res.setHeader('Transfer-Encoding', 'chunked');


  // Simulate streaming events
  let id = 0;
  const interval = setInterval(() => {
    id++;
    const event = {
      id,
      type: 'heartbeat',
      timestamp: new Date().toISOString(),
    };
    res.write(JSON.stringify(event) + '\n');


    if (id >= 100) {
      clearInterval(interval);
      res.end();
    }
  }, 100);


  req.on('close', () => clearInterval(interval));
});


app.listen(3000);
Browser: NDJSON-Stream mit Fetch verarbeiten
async function* readNdjsonStream(url) {
  const response = await fetch(url, {
    headers: { 'Accept': 'application/x-ndjson' },
  });


  const reader = response.body
    .pipeThrough(new TextDecoderStream())
    .getReader();


  let buffer = '';
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += value;
    const lines = buffer.split('\n');
    buffer = lines.pop();
    for (const line of lines) {
      if (line.trim()) yield JSON.parse(line);
    }
  }
  if (buffer.trim()) yield JSON.parse(buffer);
}


// Usage
for await (const event of readNdjsonStream('/api/events/stream')) {
  console.log('Received:', event);
}

Tools im NDJSON-Ökosystem

Immer mehr Kommandozeilentools und Bibliotheken unterstützen NDJSON nativ. Damit können Sie NDJSON-Daten filtern, transformieren und analysieren, ohne eigenen Code zu schreiben.

jq

Unverzichtbar

jq ist das beliebteste Kommandozeilentool zur Verarbeitung von JSON. Es liest standardmäßig NDJSON (einen JSON-Wert pro Zeile) und unterstützt Filtern, Mapping, Gruppieren und Neuformatieren. Mit jq -c erhalten Sie eine kompakte Ausgabe, mit jq -s laden Sie alle Datensätze in ein Array.

ndjson-cli

CLI

ndjson-cli ist eine Sammlung von Befehlen im Unix-Stil zur Verarbeitung von NDJSON-Streams: ndjson-filter, ndjson-map, ndjson-reduce, ndjson-sort und ndjson-join. Jeder Befehl liest aus stdin und schreibt nach stdout. So lassen sich die Befehle über Pipes miteinander verknüpfen.

ndjson (npm)

Node.js

Das npm-Paket ndjson bietet NDJSON-Parser und -Serialisierer für Streaming in Node.js. Es stellt die Transform-Streams ndjson.parse() und ndjson.stringify() bereit, die sich direkt in die Stream-Pipelines von Node.js einbinden lassen, um Daten mit hohem Durchsatz zu verarbeiten.

NDJSON und JSONL: Interoperabilität

NDJSON und JSONL (JSON Lines) sind funktional identische Formate. Beide speichern einen JSON-Wert pro Zeile, wobei Zeilenumbruchzeichen die Werte voneinander trennen. Eine gültige NDJSON-Datei ist auch eine gültige JSONL-Datei und umgekehrt. Sie können eine .ndjson-Datei in .jsonl umbenennen oder umgekehrt, ohne ein einziges Byte am Inhalt zu ändern. Jedes Tool, das eines der Formate lesen kann, kann auch das andere lesen.

Die Unterschiede betreffen lediglich die Benennung: NDJSON geht auf github.com/ndjson/ndjson-spec zurück und verwendet die Dateiendung .ndjson sowie den MIME-Typ application/x-ndjson. JSONL stammt von jsonlines.org und nutzt die Dateiendung .jsonl. In der Praxis verwenden die meisten Entwickler beide Namen synonym. Wenn Ihr Projekt bereits JSONL nutzt, müssen Sie nicht zu NDJSON wechseln. Gibt eine Bibliothek an, NDJSON zu unterstützen, funktioniert sie auch ohne Änderungen mit Ihren .jsonl-Dateien.

JSONL und NDJSON im Detailvergleich

Mehr zur Geschichte, zu den Unterschieden zwischen den Spezifikationen und zur Verbreitung von JSONL und NDJSON in der Community erfahren Sie in unserem ausführlichen Vergleich.

NDJSON-Dateien online bearbeiten

Zeigen Sie NDJSON- und JSONL-Dateien bis zu 1 GB direkt im Browser an, validieren und konvertieren Sie sie. Kein Upload erforderlich, 100 % privat.

Häufig gestellte Fragen

Quellen