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.
{
"$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.
{"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.
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.
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.
# 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
fiAutomatiser 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.
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.
// 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.
// 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.
// 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": trueValider des fichiers JSONL en ligne
Vous souhaitez vérifier rapidement vos données JSONL sans écrire de script ? Nos outils gratuits vous permettent de valider, de formater et d’examiner vos fichiers JSONL dans votre navigateur. Tous les traitements s’effectuent localement : vos données restent privées.
Validez vos fichiers JSONL ligne par ligne. Repérez immédiatement les erreurs de syntaxe et les problèmes d’encodage ou de format.
Maîtrisez les bonnes pratiques JSONL : mise en forme, cohérence des schémas, gestion des erreurs, optimisation des performances et organisation des fichiers. Des exemples concrets vous aident à éviter les pièges courants.
Un guide complet pour préparer vos fichiers JSONL destinés à OpenAI : format des données de fine-tuning, requêtes de l’API Batch, erreurs courantes et conseils de validation.
Les stratégies pour traiter des gigaoctets de données JSONL : lecture en streaming, gestion de la mémoire, découpage des fichiers, compression et outils en ligne.
Un guide complet pour manipuler des fichiers JSONL en Python. Apprenez à lire, écrire et parser du JSONL avec json, pandas et orjson, et à utiliser le streaming pour les fichiers volumineux.