JSONL-schemavalidatie: zorg voor betrouwbare data
Een uitgebreide gids voor het valideren van JSONL-bestanden met JSON Schema. Leer hoe je schema's definieert, records valideert in Python en Node.js, controles automatiseert in CI/CD-pipelines en de oorzaak van veelvoorkomende validatiefouten achterhaalt.
Waarom schemavalidatie nodig is voor JSONL-bestanden
JSONL-bestanden (JSON Lines) worden veel gebruikt voor het inlezen van logs, datasets voor machine learning, API-batchverwerking en datapipelines. Elke regel is een zelfstandig JSON-object. Daardoor is er geen ingebouwde controle die ervoor zorgt dat alle records dezelfde structuur hebben. Eén verkeerd opgebouwde regel, een ontbrekend verplicht veld of een onverwacht datatype kan ongemerkt fouten veroorzaken in de verdere verwerking, modeltraining laten vastlopen of API-batchtaken halverwege laten mislukken.
Schemavalidatie lost dit op met een formeel contract waaraan elk record moet voldoen. JSON Schema is de gangbare standaard om de structuur, datatypes en voorwaarden van JSON-data vast te leggen. Door elke regel van een JSONL-bestand aan een JSON Schema te toetsen voordat de data je pipeline ingaat, spoor je fouten vroeg op, besteed je minder tijd aan debuggen en waarborg je ook bij grote hoeveelheden data de kwaliteit. Deze gids neemt je mee door het hele proces: van je eerste schema tot validatie in geautomatiseerde CI/CD-workflows.
De basis van JSON Schema voor JSONL
JSON Schema is een declaratieve taal waarmee je beschrijft hoe een JSON-object eruit moet zien. Je legt onder meer vast welke velden verplicht zijn, welke datatypes ze moeten hebben, binnen welk bereik waarden mogen vallen en aan welke patronen strings moeten voldoen. Bij JSONL-validatie toets je elke regel in het bestand aan hetzelfde schema. Zo hebben alle records een consistente structuur, wat essentieel is voor betrouwbare dataverwerking.
Hieronder zie je een JSON Schema voor een record dat een gebruikersactie vastlegt. De velden id (integer), event (string uit een vaste reeks waarden) en timestamp (ISO 8601-formaat) zijn verplicht; het metadata-object is optioneel. Het veld additionalProperties staat op false, zodat onverwachte sleutels worden geweigerd.
{
"$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
}Dit JSONL-bestand bevat records die aan het bovenstaande schema voldoen. Elke regel is een zelfstandig JSON-object dat één gebruikersactie vastlegt. Het optionele metadata-veld staat wel op sommige regels en niet op andere. Beide varianten zijn geldig volgens het schema.
{"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"}JSONL-bestanden valideren met Python, Node.js en de CLI
Er zijn verschillende beproefde tools om JSONL aan een JSON Schema te toetsen. Welke het beste past, hangt af van je bestaande stack. Python-ontwikkelaars gebruiken meestal de jsonschema-library en JavaScript-ontwikkelaars kiezen vaak voor Ajv. Teams die liever met shellscripts werken, kunnen een validator voor de commandline gebruiken. Hieronder vind je alle drie de aanpakken.
De jsonschema-library is het populairste Python-package voor JSON Schema-validatie. Je installeert het met pip install jsonschema. Het onderstaande script leest een JSONL-bestand regel voor regel, valideert elk record en verzamelt alle fouten met de bijbehorende regelnummers. Dat maakt debuggen eenvoudiger.
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) is de snelste JSON Schema-validator voor JavaScript. Je installeert deze met npm install ajv ajv-formats. Het package ajv-formats voegt ondersteuning toe voor format-keywords zoals date-time. Dit script leest het JSONL-bestand als stream regel voor regel in om het geheugengebruik laag te houden.
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!');
}Voor een snelle, eenmalige controle of een workflow met shellscripts kun je jq en ajv-cli combineren. De onderstaande aanpak splitst het JSONL-bestand op in afzonderlijke JSON-objecten en toetst elk object aan het schema. Handig als je daar geen eigen script voor wilt schrijven.
# 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
fiValidatie automatiseren in CI/CD-pipelines
Voor kleine datasets kun je handmatig valideren, maar in productieworkflows is automatisering nodig. Als je JSONL-schemavalidatie in je CI/CD-pipeline opneemt, wordt elke wijziging in de data gecontroleerd voordat die in productie terechtkomt. Zo voorkom je dat ongeldige data in je datawarehouse belandt, modeltraining laat vastlopen of API-batchtaken verstoort. Hieronder staat een GitHub Actions-workflow die JSONL-bestanden bij elke push en pull request valideert.
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!')
"Deze workflow start alleen wanneer JSONL-bestanden in de map data veranderen, zodat CI snel blijft. Het validatiescript laadt het schema één keer en controleert alle JSONL-bestanden in die map en de onderliggende mappen. Als een record niet door de validatie komt, stopt de workflow met een exitcode ongelijk aan nul. Daarmee wordt de merge geblokkeerd. Je kunt deze aanpak uitbreiden met meerdere schema's voor verschillende bestandstypen, Slack-meldingen bij fouten of validatierapporten die je als build-artifacts uploadt.
Veelvoorkomende validatiefouten en hoe je ze oplost
Als je voor het eerst schemavalidatie op een bestaande JSONL-dataset toepast, komen er vaak verborgen problemen met de datakwaliteit aan het licht. Hieronder staan de drie meest voorkomende validatiefouten en hoe je ze oplost.
Niet-overeenkomend gegevenstype
Een type mismatch ontstaat als een veld een waarde van het verkeerde type bevat. Meestal gaat het om numerieke ID's die als strings zijn opgeslagen, bijvoorbeeld bij een export uit een spreadsheet of CSV-bestand. Los dit op door de waarde tijdens je ETL-proces naar het juiste type te casten. Als beide types geldig zijn, kun je ook het schema aanpassen zodat het meerdere types accepteert.
// 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)Ontbrekende verplichte velden
Deze fout betekent dat in een record een eigenschap ontbreekt die in de required-array van het schema staat. Dit gebeurt vaak wanneer aanleverende systemen hun uitvoerformaat wijzigen of optionele velden per ongeluk worden weggelaten. Laat je datapipeline in dat geval een standaardwaarde invullen, of pas het schema aan om het veld optioneel te maken als het inderdaad niet altijd aanwezig is.
// 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"]Onverwachte extra eigenschappen
Als additionalProperties in je schema op false staat, leidt elk veld dat niet expliciet in properties staat tot een validatiefout. Dat is streng, maar helpt om typefouten en datalekken op te sporen. Wil je extra velden toestaan, zet additionalProperties dan op true of gebruik patternProperties om een patroon voor toegestane veldnamen vast te leggen.
// 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": trueJSONL-bestanden online valideren
Wil je snel je JSONL-data controleren zonder een script te schrijven? Met onze gratis tools kun je JSONL-bestanden in je browser valideren, formatteren en bekijken. Alles wordt lokaal in je browser verwerkt, dus je data blijft privé.
Valideer JSONL-bestanden regel voor regel. Spoor syntaxfouten, tekencoderingsproblemen en fouten in het formaat direct op.
Leer de best practices voor JSONL toepassen: opmaak, consistente schema’s, foutafhandeling, prestatieoptimalisatie en het organiseren van bestanden. Vermijd veelvoorkomende valkuilen aan de hand van praktische voorbeelden.
Een complete handleiding om JSONL-bestanden voor OpenAI voor te bereiden. Met uitleg over het dataformaat voor fine-tuning, Batch API-requests, veelgemaakte fouten en tips voor validatie.
Strategieën om gigabytes aan JSONL-data te verwerken. Met aandacht voor lezen via streaming, geheugenbeheer, het splitsen van bestanden, compressie en online tools.
Een complete handleiding om met JSONL-bestanden in Python te werken. Leer JSONL lezen, schrijven en parsen met json, pandas en orjson, en gebruik streaming voor grote bestanden.