Di Jerry Fan

JSON e JSONL: qual è la differenza?

Una guida completa ai formati JSON e JSONL (JSON Lines): cosa cambia e quando usare l’uno o l’altro.

Confronto rapido

CaratteristicaJSONJSONL (JSON Lines)
StrutturaUn singolo oggetto o arrayUn oggetto JSON per riga
Estensione del file.json.jsonl o .ndjson
ParsingRichiede il parsing dell’intero fileConsente il parsing riga per riga
StreamingDifficileSupporto nativo
Gestione di file di grandi dimensioniConsumo elevato di memoriaConsumo ridotto di memoria
LeggibilitàFormattato con indentazioneCompatto, un record per riga
Validazione con JSON SchemaSupporta JSON SchemaJSON Schema applicato a ogni riga
Aggiunta di datiRichiede la riscrittura dell’intero fileBasta aggiungere una nuova riga

Cos'è JSON?

JSON (JavaScript Object Notation) è un formato leggero per lo scambio di dati, facile da leggere e scrivere per le persone e da interpretare e generare per i programmi. Si basa su un sottoinsieme di JavaScript ed è diventato lo standard de facto per lo scambio di dati sul web.

Un file JSON contiene un unico valore JSON, in genere un oggetto o un array. Per accedere ai dati al suo interno, è necessario eseguire il parsing dell’intero file come un’unica unità.

Esempio di JSON
[
  {"name": "Alice", "age": 30, "city": "New York"},
  {"name": "Bob", "age": 25, "city": "London"},
  {"name": "Charlie", "age": 35, "city": "Tokyo"}
]

Cos'è JSONL (JSON Lines)?

JSONL (JSON Lines), noto anche come Newline Delimited JSON (NDJSON), è un formato di testo in cui ogni riga contiene un oggetto JSON valido. Le righe sono separate da caratteri di fine riga (\n). A differenza del JSON standard, i dati non sono racchiusi in un array o in un oggetto esterno.

Ogni riga di un file JSONL è autonoma e può essere interpretata separatamente. Per questo JSONL è ideale per lo streaming di dati, i file di log e l’elaborazione di dataset di grandi dimensioni senza dover caricare tutto in memoria.

Esempio di JSONL
{"name": "Alice", "age": 30, "city": "New York"}
{"name": "Bob", "age": 25, "city": "London"}
{"name": "Charlie", "age": 35, "city": "Tokyo"}

Differenze principali tra JSON e JSONL

1. Formato e struttura del file

JSON

JSON racchiude tutti i dati in un unico oggetto o array. Il file deve essere sintatticamente valido nel suo insieme: basta una parentesi mancante alla fine per rendere non valido l’intero file.

JSONL

JSONL memorizza un oggetto JSON per riga. Ogni riga è indipendente: se una contiene un errore, è comunque possibile eseguire il parsing delle altre.

2. Parsing e consumo di memoria

JSON

JSON richiede di caricare l’intero file ed eseguirne il parsing in una sola volta. Per il parsing di un file JSON da 1 GB servirebbe circa 1 GB o più di memoria.

JSONL

JSONL consente la lettura e il parsing riga per riga (streaming). Leggendo una riga alla volta, puoi elaborare anche un file JSONL da 10 GB con un consumo minimo di memoria.

3. Streaming e dati in tempo reale

JSON

JSON non è progettato per lo streaming. Per iniziare a elaborare i dati, devi aver ricevuto l’intero file o l’intera risposta e averne completato il parsing.

JSONL

JSONL è ideale per lo streaming. Ogni riga può essere elaborata appena arriva: questo lo rende perfetto per flussi di dati in tempo reale, log e server-sent events.

4. Aggiunta e scrittura dei dati

JSON

Per aggiungere dati a un array JSON devi leggere l’intero file, eseguirne il parsing, aggiungere il nuovo elemento e riscrivere tutto il file.

JSONL

Per aggiungere dati a un file JSONL basta inserire una nuova riga in fondo al file, senza leggere o modificare i dati esistenti. La complessità è O(1), rispetto a O(n) per JSON.

5. Leggibilità

JSON

JSON supporta la formattazione con indentazione (pretty-printing), che rende molto leggibili i file di configurazione e le risposte delle API.

JSONL

JSONL è pensato per essere compatto, con un record per riga. È ottimizzato per l’elaborazione da parte dei programmi più che per la lettura da parte delle persone, anche se è possibile formattare le singole righe con il pretty-printing.

Quando usare JSON e quando JSONL

JSONUsa JSON quando:
  • Lavori con file di configurazione
  • Crei i body delle richieste e delle risposte di API REST
  • Memorizzi dati strutturati di piccole dimensioni (meno di 10 MB)
  • I dati devono essere leggibili e modificabili a mano
  • Lavori con strutture dati annidate e gerarchiche
  • Scambi dati lato browser
JSONLUsa JSONL quando:
  • Elabori dataset di grandi dimensioni (100 MB o più)
  • Trasmetti dati in streaming in tempo reale
  • Scrivi file di log e dati relativi agli eventi
  • Addestri modelli di machine learning (OpenAI, Hugging Face)
  • Lavori con pipeline ETL ed elaborazione dei dati
  • Aggiungi dati di frequente
  • Elabori dati con strumenti Unix (grep, awk, sed)

Casi d'uso comuni

Machine learning e AI

JSONL

JSONL è il formato standard per i dati di addestramento dei modelli di machine learning. OpenAI lo usa per i dataset di fine-tuning e molti framework di machine learning richiedono dati in input in formato JSONL. Ogni riga rappresenta un esempio di addestramento.

Logging delle applicazioni

JSONL

JSONL si presta bene ai log dei server, agli eventi delle applicazioni e agli audit trail. Ogni evento viene scritto su una sola riga: è quindi facile aggiungere nuovi eventi, cercarli con grep ed elaborarli con strumenti di streaming.

API web e configurazione

JSON

Le API REST usano in genere JSON per i body delle richieste e delle risposte. I file di configurazione (.json) usano JSON per rappresentare impostazioni leggibili e strutturate, con oggetti annidati.

Big data e analisi

JSONL

Le pipeline di dati, i processi ETL e gli strumenti di analisi usano JSONL per elaborare grandi volumi di dati. Ogni record può essere elaborato in modo indipendente, consentendo l’elaborazione parallela e l’uso di pattern MapReduce.

Esempi di codice

Leggere JSON in JavaScript
// Reading JSON - must load entire file
const data = JSON.parse(fs.readFileSync('data.json', 'utf8'));


// Access data
data.forEach(item => {
  console.log(item.name);
});
Leggere JSONL in JavaScript
// Reading JSONL - stream line by line
import { createReadStream } from 'fs';
import { createInterface } from 'readline';


const rl = createInterface({
  input: createReadStream('data.jsonl')
});


for await (const line of rl) {
  const item = JSON.parse(line);
  console.log(item.name);
}
Convertire JSON in JSONL
// JSON array to JSONL
const jsonArray = JSON.parse(fs.readFileSync('data.json', 'utf8'));
const jsonl = jsonArray
  .map(item => JSON.stringify(item))
  .join('\n');
fs.writeFileSync('data.jsonl', jsonl);
Convertire JSONL in JSON
// JSONL to JSON array
const lines = fs.readFileSync('data.jsonl', 'utf8')
  .split('\n')
  .filter(line => line.trim());
const jsonArray = lines.map(line => JSON.parse(line));
fs.writeFileSync('data.json', JSON.stringify(jsonArray, null, 2));

Prova il nostro visualizzatore JSONL

Visualizza e modifica subito file JSONL fino a 1 GB nel browser, senza caricare file né registrarti.

Domande frequenti

Riferimenti