Door Jerry Fan

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.

Een JSON Schema definiëren
{
  "$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.

Voorbeeld van JSONL-data
{"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.

Python met 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) 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.

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

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.

Valideren via de commandline
# 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

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

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

Voorbeeld: ID als string in plaats van integer
// 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.

Voorbeeld: ontbrekend timestamp-veld
// 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.

Voorbeeld: onbekend veld in een 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

Valideer je JSONL-bestanden meteen

Upload je JSONL-bestand en controleer het meteen op syntaxfouten, structuurproblemen en opmaakproblemen. Je bestand wordt niet naar een server geüpload: 100% privé.

Veelgestelde vragen

Bronnen