NDJSON Complete Gids: Newline Delimited JSON Uitgelegd

De NDJSON-specificatie

De officiële NDJSON-specificatie op github.com/ndjson/ndjson-spec is opzettelijk minimaal. Het definieert een eenvoudige conventie voor het serialiseren van meerdere JSON-waarden in een enkele tekststroom. De kernregels zijn eenvoudig:

De specificatie vermijdt bewust het toevoegen van headers, metadata of schema-informatie aan het formaat. Dit houdt NDJSON zo eenvoudig mogelijk en compatibel met standaard Unix-tekstverwerkingstools. Elke geldige JSON-waarde is toegestaan op elke regel, hoewel in de praktijk de meeste NDJSON-bestanden JSON-objecten bevatten met een consistente set sleutels.

• Elke regel MOET precies één geldige JSON-waarde bevatten (object, array, string, nummer, boolean of null).
• Regels worden gescheiden door het newline-teken '\n' (U+000A). De carriage return '\r' (U+000D) mag vóór '\n' verschijnen maar is niet vereist.
• Een afsluitende newline na de laatste JSON-waarde is toegestaan maar niet vereist.
• Elke JSON-waarde mag geen ongeëscapete newline-tekens bevatten binnen de waarde zelf.

Omdat de regels minimaal zijn, is NDJSON eenvoudig te genereren vanuit elke programmeertaal die een JSON-serializer heeft. Serialiseer gewoon elk record, voeg een newline toe en schrijf het naar de uitvoer. Geen sluitende haakjes, geen achterliggende komma's, geen omsluitende arraystructuur om je zorgen over te maken.

NDJSON MIME-type: application/x-ndjson

Het geregistreerde MIME-type voor NDJSON is application/x-ndjson. Dit content type wordt gebruikt in HTTP-headers om aan te geven dat de response body newline-gescheiden JSON-gegevens bevat. Veel streaming API's, waaronder de GitHub API, Docker Registry API en Elasticsearch bulk API, gebruiken dit MIME-type om NDJSON-responses te leveren.

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

Sommige API's accepteren ook application/json-seq (RFC 7464) of text/plain als alternatieven. Echter, application/x-ndjson is het meest wijdverbreide MIME-type voor newline-gescheiden JSON-streams. Wanneer je een nieuwe API bouwt die JSON-records streamt, gebruik dan application/x-ndjson voor maximale compatibiliteit.

NDJSON in HTTP Streaming API's

NDJSON is de de facto standaard voor HTTP-streaming API's die realtime gegevens leveren. Wanneer een server een NDJSON-response verstuurt, kan de client beginnen met het verwerken van het eerste record zodra het binnenkomt, zonder te wachten tot de volledige response compleet is. Dit is sneller en geheugenefficiënter dan het retourneren van een grote JSON-array.

Populaire diensten die NDJSON-streaming gebruiken zijn Docker Registry (image layer events), Elasticsearch (bulkoperaties), Apache CouchDB (changes feed) en veel moderne event-driven API's. Het patroon werkt goed met Server-Sent Events-alternatieven, realtime log-tailing en progressief laden van gegevens in webapplicaties.

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 en JSONL: Interoperabiliteit

NDJSON en JSONL (JSON Lines) zijn functioneel identieke formaten. Beide slaan één JSON-waarde per regel op, gescheiden door newline-tekens. Een bestand dat geldig NDJSON is, is ook geldig JSONL, en vice versa. Je kunt een .ndjson-bestand hernoemen naar .jsonl (of andersom) zonder een enkele byte inhoud te wijzigen, en elke tool die het ene formaat leest, zal het andere ook lezen.

De enige verschillen zijn cosmetisch: NDJSON komt van github.com/ndjson/ndjson-spec en gebruikt de .ndjson-extensie met het application/x-ndjson MIME-type, terwijl JSONL van jsonlines.org komt en de .jsonl-extensie gebruikt. In de praktijk behandelen de meeste ontwikkelaars de twee namen als synoniemen. Als je project al JSONL gebruikt, is er geen reden om naar NDJSON te migreren, en als een bibliotheek zegt NDJSON te ondersteunen, werkt het zonder enige wijziging met je .jsonl-bestanden.