Di Jerry Fan

Best practice per JSONL

Una guida completa per scrivere file JSONL ben strutturati, affidabili e performanti. Scopri le regole di formattazione, come progettare lo schema, le strategie di gestione degli errori e le tecniche di ottimizzazione per i carichi di lavoro in produzione.

Perché seguire le best practice per JSONL

JSONL (JSON Lines) sembra semplicissimo: un oggetto JSON per riga, con un carattere di fine riga come separatore. Questa semplicità, però, non esclude la possibilità di commettere errori. Schemi incoerenti, problemi di codifica, virgole finali e caratteri di fine riga incorporati sono tra le cause più comuni degli errori di parsing nelle pipeline di dati in produzione. Seguire un insieme chiaro di buone pratiche permette di prevenire questi problemi.

Questa guida illustra le regole essenziali per generare e leggere dati JSONL in modo affidabile. Che tu stia creando dataset per il machine learning, trasmettendo log applicativi in streaming o scambiando dati tra servizi, queste pratiche ti aiuteranno a evitare bug difficili da individuare e a migliorare le prestazioni dei tuoi workflow JSONL.

Regole di formattazione

Per ottenere file JSONL validi, devi rispettare rigorosamente alcune regole di formattazione. Basta violarne una perché la maggior parte dei parser rifiuti il file.

Ogni riga di un file JSONL deve contenere un valore JSON completo e autonomo. Non distribuire mai un singolo oggetto JSON su più righe. Il JSON formattato con indentazione non è JSONL valido. Serializza sempre in formato compatto, senza indentazione né spazi aggiuntivi tra chiavi e valori.

Un oggetto JSON per riga
# Valid JSONL - one complete JSON per line
{"id":1,"name":"Alice","tags":["admin","user"]}
{"id":2,"name":"Bob","tags":["user"]}


# INVALID - pretty-printed JSON spans multiple lines
{
  "id": 1,
  "name": "Alice"
}

I file JSONL devono essere codificati in UTF-8: è la codifica prevista da praticamente tutti i parser JSONL, gli strumenti di streaming e i servizi cloud. Evita UTF-16, Latin-1 e altre codifiche. Se i dati di origine usano una codifica diversa, convertili in UTF-8 prima di scriverli in formato JSONL.

Usa sempre la codifica UTF-8
# Python: always specify UTF-8 when reading/writing
with open('data.jsonl', 'w', encoding='utf-8') as f:
    f.write(json.dumps(record, ensure_ascii=False) + '\n')


# Node.js: UTF-8 is the default for fs
fs.appendFileSync('data.jsonl', JSON.stringify(record) + '\n', 'utf-8');

Usa un singolo carattere line feed (LF, \n) come separatore di riga. È lo standard su Linux, macOS e nella maggior parte degli ambienti cloud. Evita la sequenza carriage return + line feed (CRLF, \r\n) usata da Windows, perché può causare problemi di parsing. La maggior parte degli editor e degli strumenti moderni gestisce automaticamente i caratteri di fine riga, ma controlla le impostazioni se lavori su più piattaforme.

Scegli il carattere di fine riga
# Correct: LF line endings (\n)
{"id":1}\n{"id":2}\n


# Avoid: CRLF line endings (\r\n)
{"id":1}\r\n{"id":2}\r\n


# Tip: configure Git to normalize line endings
# .gitattributes
*.jsonl text eol=lf

Coerenza dello schema

JSONL non impone uno schema, ma mantenerlo coerente tra i record rende i dati molto più semplici da gestire. Schemi incoerenti possono causare errori a runtime, valori null imprevisti e importazioni non riuscite.

Usa gli stessi nomi dei campi, lo stesso ordine e gli stessi tipi di valore in tutti i record. JSON non impone un ordine per i campi, ma mantenerlo uniforme migliora la leggibilità e favorisce la compressione. Non usare mai tipi diversi per lo stesso campo: ad esempio, un campo "price" non deve essere una stringa in alcuni record e un numero in altri.

Mantieni coerenti nomi, ordine e tipi dei campi
# Good: consistent field order and types
{"id":1,"name":"Alice","age":30,"active":true}
{"id":2,"name":"Bob","age":25,"active":false}
{"id":3,"name":"Charlie","age":35,"active":true}


# Bad: inconsistent order, mixed types, missing fields
{"name":"Alice","id":1,"active":true}
{"id":"2","age":25,"name":"Bob"}
{"id":3,"active":"yes","name":"Charlie"}

Quando un campo non ha un valore, includilo comunque assegnandogli il valore JSON null, invece di omettere del tutto la chiave. In questo modo, ogni record contiene lo stesso insieme di chiavi e l’elaborazione nelle fasi successive diventa più semplice. Il codice che legge i dati non deve distinguere tra "campo mancante" e "campo null".

Gestisci esplicitamente i valori mancanti
# Good: include all fields, use null for missing values
{"id":1,"name":"Alice","email":"[email protected]","phone":null}
{"id":2,"name":"Bob","email":null,"phone":"+1-555-0100"}


# Avoid: omitting keys for missing data
{"id":1,"name":"Alice","email":"[email protected]"}
{"id":2,"name":"Bob","phone":"+1-555-0100"}

Gestione degli errori

Nell’uso reale, i file JSONL contengono spesso alcune righe non valide dovute a problemi di codifica, scritture troncate o bug nei sistemi a monte. Un programma robusto deve saper gestire questi casi senza interrompersi alla prima riga non valida.

Racchiudi il parsing di ogni riga in un blocco try-catch e, in caso di errore, registra il numero di riga e il relativo messaggio. Puoi così saltare le righe non valide mantenendo traccia dei problemi riscontrati. Per le pipeline critiche, salva le righe non valide in un file separato, così da poterle esaminare in seguito.

Parsing tollerante agli errori con tracciamento delle righe
import json


def parse_jsonl_safe(path: str):
    """Parse JSONL with error tolerance."""
    valid, errors = [], []
    with open(path, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            try:
                valid.append(json.loads(line))
            except json.JSONDecodeError as e:
                errors.append({'line': line_num, 'error': str(e), 'raw': line})
    print(f'Parsed {len(valid)} records, {len(errors)} errors')
    return valid, errors

Nelle pipeline di dati, aggiungi una fase di validazione prima dell’elaborazione principale. Verifica che ogni record contenga i campi previsti e che i tipi siano corretti. Scarta o metti in quarantena i record che non rispettano questi requisiti. Eviterai così che gli errori di tipo emergano nelle fasi avanzate della pipeline, dove è più difficile individuarne la causa.

Valida i dati prima di elaborarli
def validate_record(record: dict) -> list[str]:
    """Validate a JSONL record against expected schema."""
    issues = []
    required = ['id', 'name', 'timestamp']
    for field in required:
        if field not in record:
            issues.append(f'Missing required field: {field}')
    if 'id' in record and not isinstance(record['id'], int):
        issues.append(f'Field "id" should be int, got {type(record["id"]).__name__}')
    return issues


# Usage in pipeline
for record in parse_jsonl_safe('data.jsonl')[0]:
    issues = validate_record(record)
    if issues:
        log_warning(f'Record {record.get("id")}: {issues}')
    else:
        process(record)

Ottimizzazione delle prestazioni

Nei workflow di data engineering e machine learning, i file JSONL possono raggiungere dimensioni di diversi gigabyte. Una strategia di elaborazione adeguata mantiene contenuto il consumo di memoria e garantisce un throughput elevato.

Non caricare mai un intero file JSONL in memoria in una sola volta. Leggi ed elabora una riga, o un batch di righe, alla volta. In questo modo il consumo di memoria rimane costante, indipendentemente dalle dimensioni del file. In Python, l’iterazione sui file avviene già riga per riga; Node.js mette a disposizione le API readline e stream per lo stesso scopo.

Elaborazione in streaming
# Python: stream with constant memory
import json


count = 0
with open('large.jsonl', 'r', encoding='utf-8') as f:
    for line in f:  # One line at a time, not f.readlines()!
        record = json.loads(line)
        process(record)
        count += 1
print(f'Processed {count} records')

Quando scrivi su un database o effettui chiamate API, raggruppa più record in batch invece di elaborarli singolarmente. Il batching riduce l’overhead di I/O e può aumentare il throughput di 10-100 volte. Per la maggior parte dei casi d’uso, i batch da 1.000-10.000 record sono una buona scelta.

Operazioni in batch
import json


def process_in_batches(path: str, batch_size: int = 5000):
    """Process JSONL records in batches for better throughput."""
    batch = []
    with open(path, 'r', encoding='utf-8') as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            batch.append(json.loads(line))
            if len(batch) >= batch_size:
                bulk_insert(batch)  # Send batch to database
                batch.clear()
    if batch:
        bulk_insert(batch)  # Flush remaining records

JSONL si presta molto bene alla compressione, perché le righe consecutive contengono spesso le stesse chiavi e valori simili. Usa gzip per l’archiviazione e il trasferimento: può ridurre le dimensioni dei file di 5-10 volte. La maggior parte dei linguaggi permette di leggere direttamente file JSONL compressi con gzip, senza prima decomprimerli su disco.

Usa la compressione per archiviare e trasferire i dati
import gzip
import json


# Write compressed JSONL
with gzip.open('data.jsonl.gz', 'wt', encoding='utf-8') as f:
    for record in records:
        f.write(json.dumps(record, ensure_ascii=False) + '\n')


# Read compressed JSONL
with gzip.open('data.jsonl.gz', 'rt', encoding='utf-8') as f:
    for line in f:
        record = json.loads(line)
        process(record)

Errori comuni da evitare

Questi sono i problemi che riscontriamo più spesso quando gli utenti validano file JSONL con i nostri strumenti. Ciascuno provoca errori di parsing che, senza il giusto approccio, possono essere difficili da diagnosticare.

JSON non ammette virgole dopo l’ultimo elemento di un oggetto o di un array. È uno degli errori più comuni, soprattutto per chi proviene da JavaScript, dove le virgole finali sono consentite. Rimuovi sempre le virgole finali dall’output.

Virgole finali
# INVALID: trailing comma after last property
{"id": 1, "name": "Alice",}


# VALID: no trailing comma
{"id": 1, "name": "Alice"}


# INVALID: trailing comma in array
{"tags": ["admin", "user",]}


# VALID: no trailing comma in array
{"tags": ["admin", "user"]}

Se una stringa contiene un carattere di fine riga letterale, viola la regola di un record per riga e rende il file JSONL non valido. All’interno delle stringhe JSON usa sempre la sequenza di escape \n, mai un carattere di fine riga letterale. La maggior parte dei serializzatori JSON lo gestisce automaticamente, ma fai attenzione se costruisci le stringhe JSON a mano.

Caratteri di fine riga nelle stringhe
# INVALID: raw newline inside a string value breaks JSONL
{"id": 1, "bio": "Line one
Line two"}


# VALID: escaped newline keeps everything on one line
{"id": 1, "bio": "Line one\nLine two"}


# Tip: json.dumps() in Python handles this automatically
import json
record = {"bio": "Line one\nLine two"}
print(json.dumps(record))
# Output: {"bio": "Line one\nLine two"}

Mescolare UTF-8 e Latin-1, o altre codifiche, nello stesso file produce caratteri illeggibili ed errori di parsing. Succede spesso quando si aggiungono dati provenienti da fonti diverse. Uniforma sempre la codifica a UTF-8 prima di scrivere i dati. Se ricevi dati con una codifica sconosciuta, identificala con una libreria come chardet prima di convertirli.

Codifiche miste o errate
# Python: detect and convert encoding
import chardet


def normalize_to_utf8(input_path: str, output_path: str):
    """Detect encoding and convert to UTF-8."""
    with open(input_path, 'rb') as f:
        raw = f.read()
    detected = chardet.detect(raw)
    encoding = detected['encoding'] or 'utf-8'
    print(f'Detected encoding: {encoding}')
    text = raw.decode(encoding)
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(text)

Nomi e organizzazione dei file

Scegliere nomi chiari per i file e una struttura ordinata per le directory rende più semplice trovare, gestire ed elaborare i dati JSONL nelle pipeline automatizzate.

Usa .jsonl come estensione predefinita. È l’estensione più diffusa per i file JSON Lines ed è quella prevista da strumenti come l’API di fine-tuning di OpenAI, BigQuery e la maggior parte delle piattaforme per la gestione dei dati. L’estensione .ndjson (Newline Delimited JSON) indica tecnicamente lo stesso formato, con un nome diverso. Scegli una convenzione e seguila in tutto il progetto.

Estensioni .jsonl e .ndjson
# Recommended file naming conventions
data.jsonl              # Standard JSONL file
users_2026-02-14.jsonl  # Date-stamped export
train.jsonl             # ML training data
validation.jsonl        # ML validation split
events.jsonl.gz         # Compressed JSONL

Organizza i file JSONL in base alla funzione e alla data. Tieni separati i dati grezzi in ingresso dai dati elaborati in uscita. Per le serie temporali e i log, usa un partizionamento per data: sarà più semplice elaborare intervalli di date specifici ed eliminare i dati meno recenti.

Struttura delle directory nei progetti JSONL
project/
  data/
    raw/                  # Original unprocessed files
      events_2026-02-13.jsonl
      events_2026-02-14.jsonl
    processed/            # Cleaned and transformed
      events_clean.jsonl
    schemas/              # Schema documentation
      event_schema.json
  scripts/
    validate.py           # Validation script
    transform.py          # Transformation pipeline

Controlla subito i tuoi file JSONL

Valida e formatta file JSONL fino a 1GB direttamente nel browser. Individua subito errori di formattazione, problemi nello schema e codifiche errate.

Domande frequenti

Riferimenti