NDJSON Komplettanleitung: Newline Delimited JSON erklart

Die NDJSON-Spezifikation

Die offizielle NDJSON-Spezifikation auf github.com/ndjson/ndjson-spec ist absichtlich minimal. Sie definiert eine einfache Konvention fur die Serialisierung mehrerer JSON-Werte in einem einzigen Textstrom. Die Kernregeln sind unkompliziert:

Die Spezifikation vermeidet bewusst das Hinzufugen von Headern, Metadaten oder Schema-Informationen zum Format. Dies halt NDJSON so einfach wie moglich und kompatibel mit Standard-Unix-Textverarbeitungstools. Jeder gultige JSON-Wert ist auf jeder Zeile erlaubt, obwohl in der Praxis die meisten NDJSON-Dateien JSON-Objekte mit einem konsistenten Satz von Schlusseln enthalten.

• Jede Zeile MUSS genau einen gultigen JSON-Wert enthalten (Objekt, Array, String, Zahl, Boolean oder null).
• Zeilen werden durch das Zeilenumbruchzeichen '\n' (U+000A) getrennt. Das Wagenrucklaufzeichen '\r' (U+000D) darf vor '\n' erscheinen, ist aber nicht erforderlich.
• Ein abschliessender Zeilenumbruch nach dem letzten JSON-Wert ist erlaubt, aber nicht erforderlich.
• Jeder JSON-Wert darf keine unmaskierten Zeilenumbruchzeichen innerhalb des Werts selbst enthalten.

Da die Regeln minimal sind, ist NDJSON leicht aus jeder Programmiersprache zu generieren, die uber einen JSON-Serialisierer verfugt. Serialisieren Sie einfach jeden Datensatz, fugen Sie einen Zeilenumbruch hinzu und schreiben Sie ihn in die Ausgabe. Keine schliessenden Klammern, keine abschliessenden Kommas, keine umschliessende Array-Struktur, um die Sie sich kummern mussen.

NDJSON-MIME-Typ: application/x-ndjson

Der registrierte MIME-Typ fur NDJSON ist application/x-ndjson. Dieser Content-Typ wird in HTTP-Headern verwendet, um anzuzeigen, dass der Antwortkorper Newline-Delimited-JSON-Daten enthalt. Viele Streaming-APIs, darunter die GitHub-API, die Docker-Registry-API und die Elasticsearch-Bulk-API, verwenden diesen MIME-Typ, um NDJSON-Antworten zu liefern.

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 Alternativen. Allerdings ist application/x-ndjson der am weitesten verbreitete MIME-Typ fur Newline-Delimited-JSON-Streams. Wenn Sie eine neue API erstellen, die JSON-Datensatze streamt, verwenden Sie application/x-ndjson fur maximale Kompatibilitat.

NDJSON in HTTP-Streaming-APIs

NDJSON ist der De-facto-Standard fur HTTP-Streaming-APIs, die Echtzeitdaten liefern. Wenn ein Server eine NDJSON-Antwort sendet, kann der Client mit der Verarbeitung des ersten Datensatzes beginnen, sobald er eintrifft, ohne auf die vollstandige Antwort zu warten. Dies ist schneller und speichereffizienter als die Ruckgabe eines grossen JSON-Arrays.

Beliebte Dienste, die NDJSON-Streaming verwenden, sind die Docker Registry (Image-Layer-Events), Elasticsearch (Bulk-Operationen), Apache CouchDB (Changes-Feed) und viele moderne ereignisgesteuerte APIs. Das Muster funktioniert gut mit Server-Sent-Events-Alternativen, Echtzeit-Log-Tailing und progressivem Datenladen in Webanwendungen.

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);

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);
}

NDJSON und JSONL: Interoperabilitat

NDJSON und JSONL (JSON Lines) sind funktional identische Formate. Beide speichern einen JSON-Wert pro Zeile, getrennt durch Zeilenumbruchzeichen. Eine Datei, die gultiges NDJSON ist, ist auch gultiges JSONL und umgekehrt. Sie konnen eine .ndjson-Datei in .jsonl umbenennen (oder umgekehrt), ohne ein einziges Byte am Inhalt zu andern, und jedes Tool, das ein Format liest, wird auch das andere lesen.

Die einzigen Unterschiede sind kosmetischer Natur: NDJSON stammt von github.com/ndjson/ndjson-spec und verwendet die .ndjson-Erweiterung mit dem MIME-Typ application/x-ndjson, wahrend JSONL von jsonlines.org stammt und die .jsonl-Erweiterung verwendet. In der Praxis behandeln die meisten Entwickler die beiden Namen als Synonyme. Wenn Ihr Projekt bereits JSONL verwendet, besteht keine Notwendigkeit, zu NDJSON zu migrieren, und wenn eine Bibliothek angibt, NDJSON zu unterstutzen, wird sie mit Ihren .jsonl-Dateien ohne Anderungen funktionieren.