Guida completa a NDJSON: il formato Newline Delimited JSON
Una guida completa a Newline Delimited JSON (NDJSON). Scopri la specifica e il tipo MIME, impara a leggere e scrivere NDJSON con Python, Node.js e da riga di comando, a usarlo nelle API HTTP in streaming e a capire il suo rapporto con JSONL.
Cos'è NDJSON?
NDJSON sta per Newline Delimited JSON. È un formato di dati testuale in cui ogni riga contiene esattamente un valore JSON valido e le righe sono separate da un carattere di fine riga (\n). È stato progettato per lo streaming e per elaborare grandi dataset senza caricare l’intero file in memoria. A differenza di un file JSON standard, che racchiude tutti i dati in un unico array o oggetto, NDJSON permette di leggere, scrivere ed elaborare un record alla volta.
La specifica NDJSON è disponibile su github.com/ndjson/ndjson-spec. È nata per formalizzare un approccio già diffuso nell’invio dei log, nelle pipeline di dati e nelle API HTTP in streaming. Ogni riga è indipendente: se una contiene JSON non valido, è comunque possibile eseguire il parsing delle altre. Questo rende NDJSON tollerante agli errori e particolarmente adatto ai flussi di lavoro append-only, come i log delle applicazioni, gli stream di eventi e le esportazioni incrementali di dati.
{"id":1,"event":"page_view","url":"/home"}
{"id":2,"event":"click","url":"/pricing"}
{"id":3,"event":"signup","url":"/register"}La specifica NDJSON
La specifica ufficiale NDJSON, disponibile su github.com/ndjson/ndjson-spec, è volutamente essenziale. Definisce una semplice convenzione per serializzare più valori JSON in un unico flusso di testo. Le regole fondamentali sono semplici:
La specifica esclude esplicitamente l’aggiunta di intestazioni, metadati o informazioni sullo schema. In questo modo, NDJSON rimane il più semplice possibile e compatibile con i normali strumenti Unix per l’elaborazione del testo. Ogni riga può contenere qualsiasi valore JSON valido, anche se, nella pratica, la maggior parte dei file NDJSON contiene oggetti JSON con un insieme uniforme 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 fine riga '\n' (U+000A). Il carattere di ritorno carrello '\r' (U+000D) può precedere '\n', ma non è obbligatorio.
- Il carattere di fine riga dopo l’ultimo valore JSON è consentito, ma non obbligatorio.
- Nessun valore JSON deve contenere al suo interno caratteri di fine riga privi di escape.
Con regole così essenziali, generare NDJSON è semplice in qualsiasi linguaggio di programmazione che disponga di un serializzatore JSON. Basta serializzare ogni record, aggiungere un carattere di fine riga e scriverlo nell’output. Non devi preoccuparti di parentesi di chiusura, virgole finali o di un array che racchiuda tutti i record.
NDJSON vs JSON vs JSONL
NDJSON, JSON e JSONL si distinguono per la struttura. Il JSON standard codifica un unico valore, di solito un array o un oggetto. JSONL e NDJSON, invece, memorizzano entrambi un valore JSON per riga e sono funzionalmente identici. La tabella seguente mette a confronto le caratteristiche principali dei tre formati.
| Caratteristica | JSON | JSONL | NDJSON |
|---|---|---|---|
| Nome completo | JavaScript Object Notation | JSON Lines | Newline Delimited JSON |
| Estensione del file | .json | .jsonl | .ndjson |
| Tipo MIME | application/json | application/jsonl (non ufficiale) | application/x-ndjson |
| Specifica | RFC 8259 (standard IETF) | jsonlines.org (comunità) | github.com/ndjson/ndjson-spec (comunità) |
| Separatore di riga | N/A (un solo valore) | \n (nuova riga) | \n (nuova riga) |
| Carattere di fine riga finale | N/A | Consigliato | Facoltativo |
| Adatto allo streaming | No (richiede il parsing dell’intero documento) | Sì (riga per riga) | Sì (riga per riga) |
Tipo MIME di NDJSON: application/x-ndjson
Il tipo MIME registrato per NDJSON è application/x-ndjson. Viene usato negli header HTTP per indicare che il corpo della risposta contiene dati JSON separati da caratteri di fine riga. Molte API in streaming, tra cui l’API di GitHub, l’API di Docker Registry e l’API bulk di Elasticsearch, usano questo tipo MIME per inviare 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ù diffuso per gli stream di valori JSON separati da caratteri di fine riga. Se sviluppi una nuova API che trasmette record JSON in streaming, usa application/x-ndjson per garantire la massima compatibilità.
Leggere e scrivere NDJSON
Lavorare con NDJSON è semplice in qualsiasi linguaggio che supporti JSON. Ecco alcuni esempi pratici per Python, Node.js e la riga di comando.
Il modulo json della libreria standard di Python consente di gestire NDJSON in modo semplice. Leggi il file una riga alla volta, esegui il parsing di ciascuna con json.loads e usa json.dumps per scrivere i dati. Con i file di grandi dimensioni, questo approccio mantiene costante l’uso della memoria.
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, usa il modulo readline insieme a fs.createReadStream per eseguire il parsing dei file NDJSON in modo efficiente. Lo stream elabora una riga alla volta, mantenendo basso l’uso della memoria indipendentemente dalle dimensioni del file.
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');Lo strumento da riga di comando jq supporta nativamente l’input NDJSON. Usa il flag --slurp per raccogliere tutti i record in un array, oppure elabora ciascun record singolarmente senza specificare alcun flag.
# 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.ndjsonNDJSON nelle API HTTP in streaming
NDJSON è lo standard di fatto per le API HTTP in streaming che trasmettono dati in tempo reale. Quando un server invia una risposta NDJSON, il client può iniziare a elaborare il primo record non appena lo riceve, senza attendere il completamento dell’intera risposta. Rispetto all’invio di un grande array JSON, questo approccio è più veloce e richiede meno memoria.
Tra i servizi più diffusi che usano lo streaming NDJSON ci sono Docker Registry (eventi relativi ai layer delle immagini), Elasticsearch (operazioni bulk), Apache CouchDB (feed delle modifiche) e molte API moderne basate su eventi. Questo approccio si presta bene alla realizzazione di alternative ai Server-Sent Events, alla lettura dei log in tempo reale e al 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);
}Strumenti dell’ecosistema NDJSON
Sono sempre più numerosi gli strumenti da riga di comando e le librerie che supportano NDJSON nativamente. Permettono di filtrare, trasformare e analizzare dati NDJSON senza dover scrivere codice su misura.
jq
Essenzialejq è lo strumento da riga di comando più diffuso per elaborare JSON. Legge NDJSON per impostazione predefinita (un valore JSON per riga) e supporta operazioni di filtro, mapping, raggruppamento e riformattazione. Usa jq -c per ottenere un output compatto e jq -s per raccogliere tutti i record in un array.
ndjson-cli
CLIndjson-cli è una raccolta di comandi in stile Unix per elaborare stream NDJSON: ndjson-filter, ndjson-map, ndjson-reduce, ndjson-sort e ndjson-join. Ogni comando legge da stdin e scrive su stdout, quindi puoi combinarli tramite pipe.
ndjson (npm)
Node.jsIl pacchetto npm ndjson offre parser e serializzatori NDJSON in streaming per Node.js. Mette a disposizione i transform stream ndjson.parse() e ndjson.stringify(), che si integrano direttamente nelle pipeline di stream di Node.js per elaborare dati con un throughput elevato.
NDJSON e JSONL: interoperabilità
NDJSON e JSONL (JSON Lines) sono formati funzionalmente identici. Entrambi memorizzano un valore JSON per riga, con un carattere di fine riga come separatore. Un file NDJSON valido è anche un file JSONL valido, e viceversa. Puoi cambiare l’estensione di un file da .ndjson a .jsonl (o viceversa) senza modificare un solo byte del contenuto: qualsiasi strumento in grado di leggere uno dei due formati leggerà anche l’altro.
Le uniche differenze sono formali: NDJSON fa riferimento a github.com/ndjson/ndjson-spec e usa l’estensione .ndjson con il tipo MIME application/x-ndjson, mentre JSONL fa riferimento a jsonlines.org e usa l’estensione .jsonl. Nella pratica, la maggior parte degli sviluppatori considera i due nomi sinonimi. Se il tuo progetto usa già JSONL, non serve migrare a NDJSON. Allo stesso modo, una libreria che dichiara di supportare NDJSON funzionerà con i tuoi file .jsonl senza alcuna modifica.
Prova i nostri strumenti gratuiti per NDJSON e JSONL
Lavora con i file NDJSON e JSONL direttamente nel browser. Tutti i dati vengono elaborati in locale, così la loro riservatezza è garantita.
Approfondisci il rapporto tra JSONL e NDJSON (Newline Delimited JSON). Scopri le piccole differenze e quando usare ciascun termine.
Valida i file JSONL riga per riga. Individua subito errori di sintassi e problemi di codifica o di formato.
Impara a elaborare dati JSONL in streaming in tempo reale con Node.js, Python, Server-Sent Events e WebSocket. Crea pipeline di streaming per log, metriche e flussi di dati in tempo reale.
Scopri cos’è JSONL (JSON Lines), in cosa si distingue dal normale JSON e perché è il formato preferito per lo streaming di dati, i file di log e i dataset di machine learning.
Converti i file JSONL in un array JSON standard. Ideale per API e pipeline di elaborazione dei dati.