Di Jerry Fan

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.

Definire uno schema JSON Schema
{
  "$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.

Dati JSONL di esempio
{"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.

Python con jsonschema
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.

Node.js con Ajv
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.

Validazione da riga di comando
# 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
fi

Automatizzare 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.

Workflow GitHub Actions
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.

Esempio: ID come stringa anziché come intero
// 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.

Esempio: campo timestamp mancante
// 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.

Esempio: campo sconosciuto nel record
// 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": true

Valida subito i tuoi file JSONL

Carica il tuo file JSONL e verifica subito se contiene errori di sintassi, problemi di struttura o di formattazione. Nessun file viene inviato al server: privacy al 100%.

Domande frequenti

Riferimenti