Par Jerry Fan

Valider les fichiers JSONL avec un schéma pour garantir la qualité des données

Un guide complet pour valider vos fichiers JSONL avec JSON Schema. Apprenez à définir des schémas, à valider les enregistrements en Python et en Node.js, à automatiser les contrôles dans vos pipelines CI/CD et à diagnostiquer les erreurs de validation courantes.

Pourquoi valider les fichiers JSONL avec un schéma ?

Les fichiers JSONL (JSON Lines) sont couramment utilisés pour l’ingestion de logs, les jeux de données de machine learning, les traitements par lots via des API et les pipelines de données. Chaque ligne étant un objet JSON indépendant, aucun mécanisme intégré n’impose une structure cohérente à l’ensemble des enregistrements. Une seule ligne mal formée, un champ obligatoire manquant ou un type de données inattendu peut fausser les traitements en aval sans que cela soit détecté, faire échouer l’entraînement d’un modèle ou interrompre un traitement par lots via une API en cours d’exécution.

La validation par schéma résout ce problème en définissant un contrat formel que chaque enregistrement doit respecter. JSON Schema est le standard de référence pour décrire la structure, les types et les contraintes des données JSON. En vérifiant la conformité de chaque ligne à un schéma JSON Schema avant son entrée dans votre pipeline, vous détectez les erreurs au plus tôt, réduisez le temps de débogage et garantissez la qualité des données à grande échelle. Ce guide détaille toutes les étapes, de la rédaction de votre premier schéma à l’intégration de la validation dans des workflows CI/CD automatisés.

Les bases de JSON Schema pour les fichiers JSONL

JSON Schema est un langage déclaratif qui permet de décrire la structure attendue d’un objet JSON. Vous précisez notamment les champs obligatoires, leurs types de données, les plages de valeurs autorisées et les motifs auxquels les chaînes de caractères doivent correspondre. Pour valider un fichier JSONL, vous appliquez le même schéma à chacune de ses lignes. Tous les enregistrements suivent ainsi une structure cohérente, indispensable à la fiabilité des traitements.

Voici un exemple de schéma JSON Schema pour un enregistrement décrivant un événement utilisateur. Il impose les champs id (entier), event (chaîne choisie dans une liste de valeurs prédéfinies) et timestamp (au format ISO 8601), et autorise un objet metadata facultatif. Le paramètre additionalProperties est fixé à false pour rejeter toute clé inattendue.

Définir un schéma 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
}

Voici un fichier JSONL dont les enregistrements respectent le schéma ci-dessus. Chaque ligne contient un objet JSON autonome qui représente un événement utilisateur. Le champ facultatif metadata figure sur certaines lignes et pas sur d’autres : les deux cas sont conformes au schéma.

Exemple de données JSONL
{"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"}

Valider des fichiers JSONL avec Python, Node.js ou en ligne de commande

Plusieurs outils éprouvés permettent de vérifier la conformité de données JSONL à un schéma JSON Schema. Le choix dépend avant tout de votre stack technique. Les développeurs Python utilisent généralement la bibliothèque jsonschema, les développeurs JavaScript se tournent vers Ajv, et les équipes qui privilégient les scripts shell peuvent utiliser des validateurs en ligne de commande. Voici ces trois approches.

La bibliothèque jsonschema est le package Python le plus utilisé pour la validation avec JSON Schema. Installez-la avec pip install jsonschema. Le script ci-dessous lit un fichier JSONL ligne par ligne, valide chaque enregistrement et recense toutes les erreurs avec leur numéro de ligne pour faciliter le débogage.

Python avec 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) est le validateur JSON Schema le plus rapide pour JavaScript. Installez-le avec npm install ajv ajv-formats. Le package ajv-formats ajoute la prise en charge des formats tels que date-time. Ce script lit le fichier JSONL en streaming, ligne par ligne, pour limiter la consommation de mémoire.

Node.js avec 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!');
}

Pour des vérifications ponctuelles rapides ou des workflows reposant sur des scripts shell, vous pouvez combiner jq et ajv-cli. La méthode ci-dessous sépare le fichier JSONL en objets JSON individuels, puis vérifie la conformité de chacun au schéma. Elle est pratique si vous ne souhaitez pas écrire de script spécifique.

Validation en ligne de commande
# 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

Automatiser la validation dans les pipelines CI/CD

La validation manuelle convient aux petits jeux de données, mais les workflows de production doivent être automatisés. En intégrant la validation des fichiers JSONL par schéma à votre pipeline CI/CD, vous contrôlez chaque modification des données avant sa mise en production. Vous évitez ainsi que des données erronées n’entrent dans votre entrepôt de données, ne fassent échouer l’entraînement d’un modèle ou ne faussent les traitements par lots via des API. Voici un workflow GitHub Actions qui valide les fichiers JSONL à chaque push et à chaque 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!')
          "

Ce workflow ne se déclenche que lorsque des fichiers JSONL du répertoire data sont modifiés, ce qui permet de garder une CI rapide. Le script charge le schéma une seule fois, puis valide tous les fichiers JSONL trouvés en parcourant les sous-répertoires. Si un seul enregistrement est invalide, le workflow se termine avec un code de sortie non nul et bloque la fusion. Vous pouvez adapter cette approche en ajoutant plusieurs schémas selon les types de fichiers, en envoyant des notifications Slack en cas d’échec ou en joignant les rapports de validation aux artefacts de build.

Erreurs de validation courantes : comment les corriger

La première validation par schéma d’un jeu de données JSONL existant révèle souvent des problèmes de qualité passés inaperçus. Voici les trois erreurs les plus fréquentes et les moyens de les corriger.

Type incorrect

Cette erreur survient lorsqu’un champ contient une valeur dont le type ne correspond pas à celui attendu. Le cas le plus fréquent est celui des identifiants numériques stockés sous forme de chaînes de caractères, notamment après un export depuis un tableur ou un fichier CSV. Pour corriger le problème, convertissez la valeur dans le type attendu lors du traitement ETL, ou modifiez le schéma pour accepter plusieurs types si les deux sont valides.

Exemple : un ID sous forme de chaîne au lieu d’un entier
// 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)

Champs obligatoires manquants

Cette erreur indique qu’un enregistrement ne contient pas une propriété déclarée dans le tableau required du schéma. Elle survient généralement lorsque les systèmes en amont changent leur format de sortie ou que des champs facultatifs sont omis par erreur. Prévoyez des valeurs par défaut dans votre pipeline de données, ou modifiez le schéma pour rendre le champ facultatif si son absence est effectivement normale dans certains cas.

Exemple : champ timestamp manquant
// 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"]

Propriétés supplémentaires inattendues

Si additionalProperties vaut false dans votre schéma, tout champ qui ne figure pas explicitement dans properties provoque une erreur de validation. Cette règle stricte permet de repérer les fautes de frappe et les fuites de données. Si vous souhaitez autoriser des champs supplémentaires, passez additionalProperties à true ou utilisez patternProperties pour définir un motif auquel les noms des propriétés autorisées doivent correspondre.

Exemple : un champ inconnu dans un enregistrement
// 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

Validez vos fichiers JSONL dès maintenant

Ouvrez votre fichier JSONL pour détecter instantanément les erreurs de syntaxe, de structure et de formatage. Aucun fichier n’est envoyé à un serveur : vos données restent 100 % privées.

Questions fréquentes

Références