Validazione dei file JSONL con JSON Schema: garantire la qualità dei dati
Una guida completa alla validazione dei file JSONL con JSON Schema. Impara a definire gli schemi, validare i record in Python e Node.js, automatizzare i controlli nelle pipeline CI/CD e individuare le cause degli errori di validazione più comuni.
Perché validare i file JSONL con uno schema
I file JSONL (JSON Lines) sono molto usati per l'acquisizione dei log, i dataset di machine learning, l'elaborazione batch tramite API e le pipeline di dati. Ogni riga è un oggetto JSON indipendente, quindi non esiste un meccanismo integrato che imponga una struttura uniforme a tutti i record. Basta una riga malformata, un campo obbligatorio mancante o un tipo di dato inatteso per compromettere le elaborazioni successive senza alcuna segnalazione, interrompere l'addestramento dei modelli o far fallire a metà esecuzione i job batch delle API.
La validazione tramite schema risolve il problema definendo un contratto formale che ogni record deve rispettare. JSON Schema è lo standard di settore per descrivere la struttura, i tipi e i vincoli dei dati JSON. Se verifichi ogni riga di un file JSONL rispetto a un JSON Schema prima che entri nella pipeline, puoi rilevare subito gli errori, ridurre il tempo dedicato al debug e garantire la qualità dei dati su larga scala. Questa guida ti accompagna lungo tutto il processo, dalla stesura del primo schema all'integrazione della validazione nei workflow CI/CD automatizzati.
Le basi di JSON Schema per i file JSONL
JSON Schema è un linguaggio dichiarativo che permette di descrivere la struttura prevista di un oggetto JSON. Puoi specificare i campi obbligatori, i rispettivi tipi di dato, gli intervalli di valori ammessi, i pattern per le stringhe e altri vincoli. Nella validazione dei file JSONL, ogni riga viene verificata rispetto allo stesso schema. In questo modo tutti i record hanno una struttura uniforme, un requisito fondamentale per elaborare i dati in modo affidabile.
Ecco un esempio di JSON Schema per un record che rappresenta un evento utente. I campi obbligatori sono id (intero), event (stringa scelta da un insieme predefinito) e timestamp (in formato ISO 8601); l'oggetto metadata è facoltativo. Il campo additionalProperties è impostato su false per rifiutare qualsiasi chiave non prevista.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["id", "event", "timestamp"],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"event": {
"type": "string",
"enum": ["click", "view", "purchase", "signup"]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"properties": {
"source": { "type": "string" },
"campaign": { "type": "string" }
},
"additionalProperties": false
}
},
"additionalProperties": false
}Ecco un file JSONL con record conformi allo schema appena definito. Ogni riga è un oggetto JSON autonomo che rappresenta un evento utente. Nota che il campo facoltativo metadata compare solo in alcune righe: lo schema considera validi sia i record che lo contengono sia quelli che ne sono privi.
{"id":1,"event":"click","timestamp":"2026-02-15T10:30:00Z","metadata":{"source":"google","campaign":"spring"}}
{"id":2,"event":"purchase","timestamp":"2026-02-15T11:00:00Z"}
{"id":3,"event":"view","timestamp":"2026-02-15T11:15:00Z","metadata":{"source":"direct"}}
{"id":4,"event":"signup","timestamp":"2026-02-15T12:00:00Z"}Validare File JSONL: Python, Node.js e CLI
Esistono diversi strumenti consolidati per validare i file JSONL rispetto a un JSON Schema. La scelta dipende dallo stack che usi: chi sviluppa in Python usa in genere la libreria jsonschema, chi lavora in JavaScript si affida ad Ajv, mentre i team che preferiscono gli script shell possono usare i validatori da riga di comando. Di seguito trovi tutti e tre gli approcci.
jsonschema è il pacchetto Python più diffuso per la validazione con JSON Schema. Installalo con pip install jsonschema. Lo script seguente legge un file JSONL riga per riga, valida ogni record e raccoglie tutti gli errori con i relativi numeri di riga, per facilitare il debug.
import json
from jsonschema import validate, ValidationError
def validate_jsonl(file_path, schema):
errors = []
with open(file_path, 'r', encoding='utf-8') as f:
for line_num, line in enumerate(f, start=1):
line = line.strip()
if not line:
continue
try:
record = json.loads(line)
validate(instance=record, schema=schema)
except json.JSONDecodeError as e:
errors.append({
'line': line_num,
'error': f'Invalid JSON: {e.msg}'
})
except ValidationError as e:
errors.append({
'line': line_num,
'error': e.message,
'path': list(e.absolute_path)
})
return errors
# Load schema and validate
with open('schema.json', 'r') as f:
schema = json.load(f)
errors = validate_jsonl('data.jsonl', schema)
if errors:
print(f'Found {len(errors)} validation errors:')
for err in errors:
print(f" Line {err['line']}: {err['error']}")
else:
print('All records are valid!')Ajv (Another JSON Schema Validator) è il validatore JSON Schema più veloce per JavaScript. Installalo con npm install ajv ajv-formats. Il pacchetto ajv-formats aggiunge il supporto ai formati come date-time. Lo script legge il file JSONL in streaming, una riga alla volta, per contenere il consumo di memoria.
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';
import schema from './schema.json' assert { type: 'json' };
const ajv = new Ajv({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(schema);
async function validateJsonl(filePath) {
const errors = [];
let lineNum = 0;
const rl = createInterface({
input: createReadStream(filePath, 'utf-8'),
crlfDelay: Infinity,
});
for await (const line of rl) {
lineNum++;
const trimmed = line.trim();
if (!trimmed) continue;
try {
const record = JSON.parse(trimmed);
if (!validate(record)) {
errors.push({
line: lineNum,
errors: validate.errors.map(e =>
`${e.instancePath || '/'}: ${e.message}`
),
});
}
} catch (e) {
errors.push({ line: lineNum, errors: [`Invalid JSON: ${e.message}`] });
}
}
return errors;
}
const errors = await validateJsonl('data.jsonl');
if (errors.length) {
console.log(`Found ${errors.length} invalid records:`);
errors.forEach(e =>
console.log(` Line ${e.line}: ${e.errors.join(', ')}`)
);
process.exit(1);
} else {
console.log('All records are valid!');
}Per controlli rapidi e occasionali o per i workflow basati sulla shell, puoi combinare jq e ajv-cli. L'approccio seguente separa il file JSONL nei singoli oggetti JSON e verifica ciascuno rispetto allo schema. È utile se non vuoi scrivere uno script dedicato.
# Install ajv-cli globally
npm install -g ajv-cli ajv-formats
# Validate each line of a JSONL file against a schema
line_num=0
errors=0
while IFS= read -r line; do
line_num=$((line_num + 1))
if [ -z "$line" ]; then continue; fi
echo "$line" | ajv validate -s schema.json -d /dev/stdin --all-errors 2>/dev/null
if [ $? -ne 0 ]; then
echo " Error on line $line_num"
errors=$((errors + 1))
fi
done < data.jsonl
if [ $errors -eq 0 ]; then
echo "All records are valid!"
else
echo "Found $errors invalid records"
exit 1
fiAutomatizzare la validazione nelle pipeline CI/CD
La validazione manuale è sufficiente per piccoli dataset, ma i workflow di produzione richiedono controlli automatizzati. Integrando la validazione dei file JSONL con JSON Schema nella pipeline CI/CD, ogni modifica ai dati viene verificata prima di arrivare in produzione. Così eviti che dati errati entrino nel data warehouse, interrompano l'addestramento dei modelli o compromettano i job batch delle API. Ecco un workflow GitHub Actions che valida i file JSONL a ogni push e pull request.
name: Validate JSONL
on:
push:
paths: ['data/**/*.jsonl']
pull_request:
paths: ['data/**/*.jsonl']
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: pip install jsonschema
- name: Validate all JSONL files
run: |
python -c "
import json, glob, sys
from jsonschema import validate, ValidationError
with open('schemas/events.json') as f:
schema = json.load(f)
total_errors = 0
for path in glob.glob('data/**/*.jsonl', recursive=True):
with open(path) as f:
for num, line in enumerate(f, 1):
line = line.strip()
if not line: continue
try:
validate(json.loads(line), schema)
except (json.JSONDecodeError, ValidationError) as e:
print(f'{path}:{num}: {e}')
total_errors += 1
if total_errors:
print(f'\nFailed: {total_errors} errors found')
sys.exit(1)
print('All JSONL files are valid!')
"Il workflow si attiva solo quando vengono modificati i file JSONL nella directory data, così la CI rimane veloce. Lo script carica lo schema una sola volta e controlla tutti i file JSONL trovati con una ricerca ricorsiva. Se un record non supera la validazione, il workflow termina con un codice di uscita diverso da zero, bloccando il merge. Puoi estendere questo approccio aggiungendo schemi diversi per i vari tipi di file, inviando notifiche su Slack in caso di errore o caricando i report di validazione come artefatti della build.
Gli errori di validazione più comuni e come risolverli
Quando attivi per la prima volta la validazione tramite schema su un dataset JSONL esistente, spesso emergono problemi di qualità dei dati rimasti nascosti. Ecco i tre errori di validazione più comuni e come risolverli.
Tipo di dato errato
Questo errore si verifica quando un campo contiene un valore di un tipo diverso da quello previsto. Il caso più frequente è quello degli ID numerici memorizzati come stringhe, che si presenta quando i dati vengono esportati da fogli di calcolo o file CSV. Per risolverlo, converti il valore nel tipo corretto durante il processo ETL oppure aggiorna lo schema per accettare più tipi, se entrambi sono validi.
// Schema expects: { "type": "integer" }
// Invalid record:
{"id": "42", "event": "click", "timestamp": "2026-02-15T10:00:00Z"}
// Fix: cast to integer during processing
// Python: record['id'] = int(record['id'])
// JS: record.id = Number(record.id)Campi obbligatori mancanti
Questo errore indica che nel record manca una proprietà elencata nell'array required dello schema. In genere accade quando i sistemi a monte cambiano il formato di output o quando vengono omessi per errore dei campi facoltativi. Aggiungi alla pipeline di dati la gestione dei valori predefiniti oppure modifica lo schema per rendere il campo facoltativo, se non è effettivamente sempre presente.
// Schema requires: ["id", "event", "timestamp"]
// Invalid record (no timestamp):
{"id": 5, "event": "view"}
// Fix option 1: add default timestamp
// Python: record.setdefault('timestamp', datetime.utcnow().isoformat() + 'Z')
// Fix option 2: make timestamp optional in schema
// Change required to: ["id", "event"]Proprietà aggiuntive non previste
Se nello schema additionalProperties è impostato su false, qualsiasi campo non elencato esplicitamente in properties genera un errore di validazione. È un vincolo rigoroso, ma utile per individuare errori di battitura e fughe di dati. Se vuoi consentire campi aggiuntivi, imposta additionalProperties su true oppure usa patternProperties per definire un pattern per i nomi delle proprietà ammesse.
// Schema has: "additionalProperties": false
// Invalid record (extra field "user_agent"):
{"id": 6, "event": "click", "timestamp": "2026-02-15T14:00:00Z", "user_agent": "Mozilla/5.0"}
// Fix option 1: remove the extra field before validation
// Fix option 2: add "user_agent" to schema properties
// Fix option 3: set "additionalProperties": trueValida i file JSONL online
Vuoi controllare rapidamente i tuoi dati JSONL senza scrivere uno script? Usa i nostri strumenti gratuiti per validare, formattare ed esaminare i file JSONL nel browser. Tutta l'elaborazione avviene in locale, nel tuo browser, così i tuoi dati restano privati.
Valida i file JSONL riga per riga. Individua subito errori di sintassi e problemi di codifica o di formato.
Impara le best practice per la formattazione dei file JSONL, la coerenza dello schema, la gestione degli errori, l’ottimizzazione delle prestazioni e l’organizzazione dei file. Evita gli errori più comuni con esempi pratici.
Una guida completa alla preparazione dei file JSONL per OpenAI: formato dei dati per il fine-tuning, richieste alla Batch API, errori comuni e consigli per la validazione.
Strategie per elaborare gigabyte di dati JSONL: lettura in streaming, gestione della memoria, suddivisione dei file, compressione e strumenti online.
Una guida completa per lavorare con i file JSONL in Python. Impara a leggere, scrivere ed effettuare il parsing dei dati JSONL con json, pandas e orjson, e a usare lo streaming per i file di grandi dimensioni.