Di Jerry Fan

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
File JSONL valido
{"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

Oggetti semplici
{"id":1,"name":"Alice","email":"[email protected]"}
{"id":2,"name":"Bob","email":"[email protected]"}
{"id":3,"name":"Charlie","email":"[email protected]"}
Oggetti annidati
{"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.

Tipi diversi
{"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:

PopularFormato 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:

Riga di comando
# 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:

Python
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:

JavaScript / 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);
}

Visualizzatore JSONL online

Se preferisci un'interfaccia grafica, usa jsonl.co per aprire ed esplorare file JSONL fino a 1 GB: i file non vengono caricati su un server e tutto avviene nel tuo browser.

Come creare file JSONL

Creare un file JSONL è semplice: basta scrivere un valore JSON per riga.

Python
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')
JavaScript / Node.js
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.

JSONJSON standard
[
  {"name": "Alice", "age": 30},
  {"name": "Bob", "age": 25}
]
JSONLJSONL (JSON Lines)
{"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ù diffuso

JSONL è 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

JSONL

I 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

JSONL

Strumenti 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

JSONL

Le 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:

.jsonlL'estensione standard per JSONL, nonché la più diffusa
.ndjsonNewline Delimited JSON: tecnicamente è lo stesso formato, con un nome diverso
.jsonAlcuni strumenti generano file JSONL con estensione .json, il che può creare confusione

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 il nostro visualizzatore JSONL

Apri, visualizza e modifica file JSONL fino a 1 GB direttamente nel tuo browser. I file non vengono caricati su un server: la privacy è garantita al 100%.

Domande frequenti

Riferimenti