JSONL vs NDJSON: qual è la differenza?
Una guida completa al confronto tra JSONL (JSON Lines) e NDJSON (Newline Delimited JSON): due nomi per un formato pressoché identico, con alcune piccole differenze che vale la pena conoscere.
JSONL vs NDJSON: confronto rapido
| Caratteristica | JSONL (JSON Lines) | NDJSON |
|---|---|---|
| Nome completo | JSON Lines | Newline Delimited JSON |
| Estensione del file | .jsonl | .ndjson |
| Specifica | jsonlines.org (informale) | github.com/ndjson/ndjson-spec (specifica informale) |
| Origine | Convenzione nata nella community e diffusa dagli strumenti di data science | Proposto da Chris Olah, Thorsten Ball e altri |
| Separatore di riga | \n (newline) | \n (newline) |
| Tipo MIME | application/jsonl (non ufficiale) | application/x-ndjson |
| Supporto allo streaming | Sì, riga per riga | Sì, riga per riga |
| Adozione | OpenAI, Hugging Face, ecosistema ML/AI | Elasticsearch, Apache Spark, data engineering |
Cos'è JSONL (JSON Lines)?
JSONL, abbreviazione di JSON Lines, è un formato testuale in cui ogni riga contiene un singolo valore JSON valido. Le righe sono separate da caratteri di fine riga (\n). Il formato si è diffuso grazie alle community di machine learning e data science ed è descritto da una specifica informale su jsonlines.org.
I file JSONL usano l'estensione .jsonl. Il formato è diventato lo standard per i dati di addestramento AI e ML: OpenAI richiede file .jsonl per il fine-tuning e i dataset di Hugging Face usano comunemente il formato JSON Lines.
{"id": 1, "text": "Hello world", "label": "greeting"}
{"id": 2, "text": "How are you?", "label": "question"}
{"id": 3, "text": "Goodbye", "label": "farewell"}Cos'è NDJSON (Newline Delimited JSON)?
NDJSON, ovvero Newline Delimited JSON, è un formato in cui ogni riga contiene un valore JSON valido e le righe sono separate da caratteri di fine riga. La specifica, disponibile su github.com/ndjson/ndjson-spec, è stata formalizzata per offrire uno standard più strutturato per i dati JSON organizzati per righe.
I file NDJSON usano l'estensione .ndjson e il tipo MIME registrato application/x-ndjson. Il formato è molto diffuso nel data engineering, nell'elaborazione dei log e nelle applicazioni di streaming: lo usano Elasticsearch, Apache Spark e molte API HTTP che trasmettono dati in streaming.
{"id": 1, "text": "Hello world", "label": "greeting"}
{"id": 2, "text": "How are you?", "label": "question"}
{"id": 3, "text": "Goodbye", "label": "farewell"}JSONL e NDJSON sono lo stesso formato?
In pratica, sì: JSONL e NDJSON sono formati funzionalmente identici. Entrambi memorizzano un valore JSON per riga, con le righe separate da caratteri di fine riga (\n). Un file .jsonl e un file .ndjson che contengono gli stessi dati sono completamente intercambiabili: qualsiasi strumento in grado di leggere uno dei due formati può leggere anche l’altro.
Le differenze riguardano solo il nome, le community che li adottano e le convenzioni sui metadati. JSONL (JSON Lines) è nato nella community di data science e machine learning, mentre NDJSON (Newline Delimited JSON) è stato formalizzato dalla community di data engineering e streaming web. Pensa ai termini inglesi "movie" e "film": indicano la stessa cosa, ma in ambienti diversi si preferisce un nome o l’altro.
Le differenze più rilevanti sono l'estensione del file (.jsonl vs .ndjson) e il tipo MIME. NDJSON ha un tipo MIME più riconosciuto (application/x-ndjson), usato per lo streaming HTTP, mentre i file JSONL sono lo standard nei flussi di lavoro AI/ML. Per scegliere, segui le convenzioni del tuo ecosistema.
Differenze principali tra JSONL e NDJSON
1. Specifica e riferimento
È definito su jsonlines.org da una specifica breve e informale. Le regole sono semplici: ogni riga contiene un valore JSON valido, le righe sono separate da '\n' e la codifica UTF-8 è consigliata.
È definito su github.com/ndjson/ndjson-spec da una specifica leggermente più formale. NDJSON richiede esplicitamente che ogni riga contenga un valore JSON valido e che il separatore di riga sia '\n' (non '\r\n'); è inoltre consigliato un carattere di fine riga al termine del file.
2. Estensione del file
Usa l'estensione .jsonl, lo standard per i file di fine-tuning di OpenAI, i dataset di Hugging Face e la maggior parte degli strumenti ML/AI. GitHub e VS Code riconoscono i file .jsonl e ne evidenziano la sintassi.
Usa l'estensione .ndjson, comune negli strumenti di data engineering, nelle API bulk di Elasticsearch e nelle risposte HTTP in streaming. Molti editor supportano anche l'evidenziazione della sintassi per i file .ndjson.
3. Tipo MIME
Non ha un tipo MIME registrato ufficialmente. Tra i tipi non ufficiali più comuni ci sono application/jsonl e application/json-lines. In pratica, molti sistemi usano application/jsonl oppure ricorrono ad application/json.
Usa il tipo MIME application/x-ndjson, più riconosciuto in ambito HTTP e utilizzato da Elasticsearch, dallo standard di streaming della Fetch API e da vari framework web per le risposte in streaming.
4. Diffusione nelle community e negli ecosistemi
È il formato predominante nell'ecosistema AI/ML. OpenAI, Anthropic, Google Gemini, Hugging Face e la maggior parte dei framework ML usano .jsonl. Nel complesso, nella community degli sviluppatori il termine 'JSONL' è più conosciuto e cercato più spesso.
È il formato preferito nel data engineering e nei sistemi backend. Elasticsearch, Apache Spark, PostgreSQL COPY e molti strumenti di aggregazione dei log usano NDJSON. Il pacchetto npm ndjson conta milioni di download ogni settimana.
Quando usare JSONL e quando NDJSON
- Prepari dati di addestramento per il fine-tuning con OpenAI, Anthropic o altri LLM
- Lavori con i dataset di Hugging Face
- Crei pipeline ML e ti occupi di preprocessing dei dati
- Il tuo team o la documentazione usa il termine 'JSON Lines'
- Carichi file su piattaforme AI/ML che richiedono l'estensione .jsonl
- Lavori in ambienti di data science basati su Python
- Trasmetti dati JSON in streaming su HTTP (Server-Sent Events, streaming con fetch)
- Lavori con l'API bulk di Elasticsearch
- Crei pipeline di dati con Apache Spark o strumenti simili
- Imposti gli header Content-Type (application/x-ndjson)
- La tua infrastruttura o il tuo team segue la convenzione NDJSON
- Lavori con librerie di streaming per Node.js
Esempi di codice: leggere JSONL e NDJSON
# Reading JSONL - exactly the same as reading NDJSON
import json
with open('data.jsonl', 'r') as f:
for line in f:
record = json.loads(line.strip())
print(record['text'])
# Output:
# Hello world
# How are you?
# Goodbye// Reading NDJSON - exactly the same as reading JSONL
import { createReadStream } from 'fs';
import { createInterface } from 'readline';
const rl = createInterface({
input: createReadStream('data.ndjson')
});
for await (const line of rl) {
const record = JSON.parse(line);
console.log(record.text);
}
// Output:
// Hello world
// How are you?
// GoodbyeValida i tuoi file JSONL / NDJSON
Verifica che il tuo file .jsonl o .ndjson sia formattato correttamente. Il nostro validatore gratuito controlla che ogni riga contenga JSON sintatticamente valido.
Tutto su NDJSON: specifica, tipo MIME, lettura e scrittura in Python e Node.js, API HTTP in streaming, strumenti dell’ecosistema e rapporto con JSONL.
Valida i file JSONL riga per riga. Individua subito errori di sintassi e problemi di codifica o di formato.
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.
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.
Un confronto dettagliato tra i formati JSON e JSONL. Scopri quando usare ciascun formato, quali sono i vantaggi e gli svantaggi e come passare dall’uno all’altro.