Cos'è JSONL? Guida completa al formato JSON Lines
Tutto quello che devi sapere su JSON Lines: sintassi, esempi, casi d'uso e best practice.
Cos'è JSONL?
JSONL (JSON Lines), noto anche come Newline Delimited JSON (NDJSON), è un formato testuale in cui ogni riga contiene un valore JSON valido e le righe sono separate da caratteri di fine riga. A differenza del JSON standard, che racchiude i dati in un unico array o oggetto, JSONL memorizza un record per riga.
Questa struttura semplice rende JSONL ideale per lo streaming, il logging e l'elaborazione di dataset di grandi dimensioni: ogni riga può essere letta, interpretata ed elaborata in modo indipendente, senza caricare l'intero file in memoria.
Il formato si è diffuso grazie a strumenti e piattaforme che gestiscono grandi volumi di dati, tra cui OpenAI (per i dataset di fine-tuning), BigQuery, Apache Spark e i sistemi di gestione dei log.
Regole di sintassi di JSONL
Il formato JSONL segue poche semplici regole:
- Ogni riga deve contenere un valore JSON valido (oggetto, array, stringa, numero, booleano o null)
- Le righe sono separate da caratteri di fine riga (\n)
- Non si usano virgole né altri separatori tra le righe
- I file devono usare la codifica UTF-8
- Il carattere di fine riga al termine del file è facoltativo
- Le righe vuote vengono ignorate dalla maggior parte dei parser
{"name":"Alice","age":30,"city":"New York"}
{"name":"Bob","age":25,"city":"London"}
{"name":"Charlie","age":35,"city":"Tokyo"}Nota: ogni riga è un oggetto JSON completo e autonomo. Non ci sono virgole tra le righe e gli oggetti non sono racchiusi in un array.
Esempi di JSONL
{"id":1,"name":"Alice","email":"[email protected]"}
{"id":2,"name":"Bob","email":"[email protected]"}
{"id":3,"name":"Charlie","email":"[email protected]"}{"user":{"name":"Alice","age":30},"scores":[95,87,92]}
{"user":{"name":"Bob","age":25},"scores":[88,91,76]}Le righe di un file JSONL possono contenere valori di tipi diversi: basta che ogni riga contenga JSON valido.
{"event":"login","user":"alice","timestamp":"2026-01-15T10:30:00Z"}
{"event":"purchase","user":"alice","amount":29.99,"items":["book","pen"]}
{"event":"logout","user":"alice","timestamp":"2026-01-15T11:45:00Z"}Uno degli impieghi più diffusi di JSONL è la creazione di dataset per il fine-tuning di OpenAI:
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is JSONL?"},{"role":"assistant","content":"JSONL is a text format where each line is a valid JSON value."}]}
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"How do I read a JSONL file?"},{"role":"assistant","content":"Read the file line by line, parsing each line as JSON."}]}Come leggere i file JSONL
Puoi leggere i file JSONL con qualsiasi strumento che supporti l'elaborazione del testo riga per riga. Ecco i metodi più comuni:
Usa i normali strumenti Unix per esaminare i file JSONL:
# View first 5 lines
head -n 5 data.jsonl
# Count total lines (records)
wc -l data.jsonl
# Pretty-print each line with jq
cat data.jsonl | jq .
# Filter by field value
cat data.jsonl | jq 'select(.age > 30)'Il modulo json incluso in Python permette di gestire facilmente i file JSONL:
import json
with open('data.jsonl', 'r') as f:
for line in f:
record = json.loads(line)
print(record['name'])Leggi i file JSONL riga per riga con Node.js:
import { createReadStream } from 'fs';
import { createInterface } from 'readline';
const rl = createInterface({
input: createReadStream('data.jsonl')
});
for await (const line of rl) {
const record = JSON.parse(line);
console.log(record.name);
}Come creare file JSONL
Creare un file JSONL è semplice: basta scrivere un valore JSON per riga.
import json
records = [
{"name": "Alice", "age": 30},
{"name": "Bob", "age": 25},
{"name": "Charlie", "age": 35},
]
with open('output.jsonl', 'w') as f:
for record in records:
f.write(json.dumps(record) + '\n')import { writeFileSync } from 'fs';
const records = [
{ name: 'Alice', age: 30 },
{ name: 'Bob', age: 25 },
{ name: 'Charlie', age: 35 },
];
const jsonl = records
.map(r => JSON.stringify(r))
.join('\n');
writeFileSync('output.jsonl', jsonl + '\n');Si possono aggiungere commenti nei file JSONL?
No. La specifica JSONL non prevede commenti. Ogni riga di un file JSONL deve contenere un valore JSON valido e il formato JSON non prevede una sintassi per i commenti.
Se hai bisogno di affiancare metadati o annotazioni ai tuoi dati, puoi ricorrere ad alcune soluzioni comuni:
- 1Aggiungere un campo per i metadati agli oggetti JSON: {"_comment": "dati di test", "name": "Alice"}
- 2Usare un file di metadati separato da affiancare al file JSONL
- 3Inserire i metadati nella prima riga del file: {"_meta": {"version": "1.0", "created": "2026-01-15"}}
Tieni presente che i campi usati come "commenti" vengono interpretati come normali dati. Le applicazioni che leggono il file JSONL dovrebbero essere progettate per ignorare i campi dei metadati.
JSONL vs JSON
La differenza principale è la struttura: JSON racchiude tutti i dati in un unico valore, mentre JSONL memorizza un valore per riga.
[
{"name": "Alice", "age": 30},
{"name": "Bob", "age": 25}
]{"name":"Alice","age":30}
{"name":"Bob","age":25}- Per interpretare un file JSON occorre caricarlo interamente in memoria; un file JSONL può essere letto riga per riga
- JSON richiede virgole tra gli elementi; JSONL li separa con caratteri di fine riga
- JSON è più adatto ai file di configurazione e alle API; JSONL ai dataset di grandi dimensioni e allo streaming
- Per aggiungere dati a un file JSON occorre riscrivere l'intero file; con JSONL basta aggiungere una nuova riga in fondo
Per un confronto dettagliato, consulta la nostra guida completa JSON vs JSONL guide.
Casi d'uso comuni
Machine learning e AI
Il più diffusoJSONL è il formato standard per i dati di addestramento dei modelli di machine learning. OpenAI, Hugging Face e altre piattaforme AI lo usano per i dataset di fine-tuning perché ogni esempio di addestramento occupa una riga autonoma: questo permette di riordinare casualmente gli esempi, campionarli ed elaborarli in streaming in modo efficiente.
File di log e flussi di eventi
JSONLI sistemi di logging strutturato (ELK stack, Datadog, CloudWatch) generano log in formato JSONL. Ogni voce di log occupa una riga JSON: è quindi facile aggiungere nuove voci ed elaborare i log in tempo reale.
Elaborazione di big data
JSONLStrumenti come Apache Spark, BigQuery e AWS Athena supportano JSONL in modo nativo. La struttura a righe consente l'elaborazione parallela su sistemi distribuiti: ogni worker può elaborare un blocco di righe in modo indipendente.
API di streaming
JSONLLe API che restituiscono molti risultati usano spesso JSONL in streaming. Il client può iniziare a elaborare i risultati non appena arrivano, senza aspettare di ricevere l'intera risposta.
Estensioni dei file JSONL
Le estensioni più comuni per i file JSONL sono:
I file con queste tre estensioni contengono dati nello stesso formato: un valore JSON per riga. Il tipo MIME di JSONL è application/jsonl o application/x-ndjson.
Prova i nostri strumenti JSONL gratuiti
Verifica la sintassi dei file JSONL, convertili da un formato all'altro e visualizzali, tutto nel tuo browser.
Visualizza e modifica subito file JSONL fino a 1GB nel browser. Un lettore di file JSONL gratuito con streaming, evidenziazione della sintassi e validazione in tempo reale. Nessun upload e nessuna registrazione: i tuoi dati restano sul tuo dispositivo.
Valida i file JSONL riga per riga. Individua subito errori di sintassi e problemi di codifica o di formato.
Formatta i file JSONL con un’indentazione corretta per renderli più leggibili e facilitare il debug e la revisione dei dati.
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.
Un tutorial passo passo per lavorare con i file JSONL. Impara a leggere, scrivere ed elaborare dati JSONL con Python, JavaScript e gli strumenti da riga di comando.