Guida Completa NDJSON: Newline Delimited JSON Spiegato

La Specifica NDJSON

La specifica ufficiale NDJSON su github.com/ndjson/ndjson-spec è intenzionalmente minimale. Definisce una semplice convenzione per serializzare più valori JSON in un singolo flusso di testo. Le regole fondamentali sono dirette:

La specifica evita esplicitamente di aggiungere intestazioni, metadati o informazioni sullo schema al formato. Questo mantiene NDJSON il più semplice possibile e compatibile con gli strumenti standard di elaborazione testo Unix. Qualsiasi valore JSON valido è consentito su ogni riga, anche se nella pratica la maggior parte dei file NDJSON contiene oggetti JSON con un insieme coerente di chiavi.

• Ogni riga DEVE contenere esattamente un valore JSON valido (oggetto, array, stringa, numero, booleano o null).
• Le righe sono separate dal carattere di nuova riga '\n' (U+000A). Il ritorno a capo '\r' (U+000D) può apparire prima di '\n' ma non è richiesto.
• È consentita una nuova riga finale dopo l'ultimo valore JSON ma non è richiesta.
• Ogni valore JSON non deve contenere caratteri di nuova riga non escapati all'interno del valore stesso.

Poiché le regole sono minimali, NDJSON è facile da generare da qualsiasi linguaggio di programmazione che abbia un serializzatore JSON. Basta serializzare ogni record, aggiungere una nuova riga e scriverlo nell'output. Nessuna parentesi di chiusura, nessuna virgola finale, nessuna struttura di array che li racchiuda.

Tipo MIME NDJSON: application/x-ndjson

Il tipo MIME registrato per NDJSON è application/x-ndjson. Questo content type viene usato negli header HTTP per indicare che il corpo della risposta contiene dati JSON delimitati da nuova riga. Molte API in streaming, tra cui l'API di GitHub, l'API del Docker Registry e l'API bulk di Elasticsearch, usano questo tipo MIME per fornire risposte NDJSON.

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

Alcune API accettano anche application/json-seq (RFC 7464) o text/plain come alternative. Tuttavia, application/x-ndjson è il tipo MIME più ampiamente adottato per gli stream JSON delimitati da nuova riga. Quando costruisci una nuova API che trasmette record JSON in streaming, usa application/x-ndjson per la massima compatibilità.

NDJSON nelle API HTTP in Streaming

NDJSON è lo standard de facto per le API HTTP in streaming che forniscono dati in tempo reale. Quando un server invia una risposta NDJSON, il client può iniziare a elaborare il primo record non appena arriva, senza aspettare che l'intera risposta sia completa. Questo è più veloce e più efficiente in termini di memoria rispetto a restituire un grande array JSON.

Servizi popolari che usano lo streaming NDJSON includono Docker Registry (eventi dei layer di immagini), Elasticsearch (operazioni bulk), Apache CouchDB (feed delle modifiche) e molte API moderne event-driven. Il pattern funziona bene con alternative ai Server-Sent Events, tailing di log in tempo reale e caricamento progressivo dei dati nelle applicazioni web.

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 e JSONL: Interoperabilità

NDJSON e JSONL (JSON Lines) sono formati funzionalmente identici. Entrambi memorizzano un valore JSON per riga, separato da caratteri di nuova riga. Un file NDJSON valido è anche un file JSONL valido, e viceversa. Puoi rinominare un file .ndjson in .jsonl (o viceversa) senza cambiare un singolo byte di contenuto, e ogni strumento che legge un formato leggerà anche l'altro.

Le uniche differenze sono cosmetiche: NDJSON proviene da github.com/ndjson/ndjson-spec e usa l'estensione .ndjson con il tipo MIME application/x-ndjson, mentre JSONL proviene da jsonlines.org e usa l'estensione .jsonl. Nella pratica, la maggior parte degli sviluppatori tratta i due nomi come sinonimi. Se il tuo progetto usa già JSONL, non c'è bisogno di migrare a NDJSON, e se una libreria dice di supportare NDJSON, funzionerà con i tuoi file .jsonl senza alcuna modifica.