Door Jerry Fan

Best practices voor JSONL

Een uitgebreide gids voor het schrijven van nette, betrouwbare JSONL-bestanden die efficiënt te verwerken zijn. Leer de opmaakregels, ontwerp goede schema’s en ontdek hoe je fouten afhandelt en de verwerking in productie optimaliseert.

Waarom best practices voor JSONL belangrijk zijn

JSONL (JSON Lines) lijkt eenvoudig: één JSON-object per regel, met regeleinden als scheiding. Toch kan er van alles misgaan. Inconsistente schema’s, problemen met tekencodering, komma’s na het laatste element en regeleinden binnen strings veroorzaken vaak parsefouten in datapipelines in productie. Met een duidelijke set best practices voorkom je deze problemen.

Deze gids behandelt de belangrijkste regels om JSONL-data betrouwbaar aan te maken en te verwerken. Of je nu datasets voor machine learning samenstelt, applicatielogs streamt of data tussen services uitwisselt: met deze werkwijzen voorkom je subtiele bugs en haal je meer uit je JSONL-workflows.

Opmaakregels

Voor geldige JSONL moet je je strikt aan een paar opmaakregels houden. Wijk je daarvan af, dan wijzen de meeste parsers je bestanden af.

Elke regel in een JSONL-bestand moet een volledige, op zichzelf staande JSON-waarde bevatten. Verdeel een JSON-object nooit over meerdere regels. JSON met pretty-printing is geen geldige JSONL. Serialiseer altijd in compact formaat, zonder inspringing of extra witruimte tussen sleutels en waarden.

Eén JSON-object per regel
# Valid JSONL - one complete JSON per line
{"id":1,"name":"Alice","tags":["admin","user"]}
{"id":2,"name":"Bob","tags":["user"]}


# INVALID - pretty-printed JSON spans multiple lines
{
  "id": 1,
  "name": "Alice"
}

JSONL-bestanden moeten UTF-8 als tekencodering gebruiken. Vrijwel elke JSONL-parser, streamingtool en cloudservice gaat daarvan uit. Vermijd UTF-16, Latin-1 en andere tekencoderingen. Gebruiken je brongegevens een andere tekencodering, zet ze dan om naar UTF-8 voordat je ze als JSONL wegschrijft.

Gebruik altijd UTF-8
# Python: always specify UTF-8 when reading/writing
with open('data.jsonl', 'w', encoding='utf-8') as f:
    f.write(json.dumps(record, ensure_ascii=False) + '\n')


# Node.js: UTF-8 is the default for fs
fs.appendFileSync('data.jsonl', JSON.stringify(record) + '\n', 'utf-8');

Gebruik één line feed-teken (LF, \n) als regelscheiding. Dit is de standaard op Linux, macOS en in de meeste cloudomgevingen. Vermijd de combinatie carriage return + line feed (CRLF, \r\n) die Windows gebruikt, omdat die parseproblemen kan veroorzaken. De meeste moderne editors en tools regelen dit automatisch, maar controleer je instellingen als je op verschillende platforms werkt.

Het juiste regeleinde kiezen
# Correct: LF line endings (\n)
{"id":1}\n{"id":2}\n


# Avoid: CRLF line endings (\r\n)
{"id":1}\r\n{"id":2}\r\n


# Tip: configure Git to normalize line endings
# .gitattributes
*.jsonl text eol=lf

Een consistent schema

JSONL dwingt geen schema af, maar met een consistente structuur voor alle records zijn je gegevens veel makkelijker te verwerken. Inconsistente schema’s leiden tot fouten tijdens het uitvoeren, onverwachte null-waarden en mislukte imports.

Gebruik in alle records dezelfde veldnamen, veldvolgorde en datatypen. JSON stelt geen eisen aan de veldvolgorde, maar een vaste volgorde maakt de data beter leesbaar en beter te comprimeren. Gebruik voor hetzelfde veld nooit verschillende datatypen: een veld "price" mag bijvoorbeeld niet in sommige records een string zijn en in andere een getal.

Consistente veldvolgorde en datatypen
# Good: consistent field order and types
{"id":1,"name":"Alice","age":30,"active":true}
{"id":2,"name":"Bob","age":25,"active":false}
{"id":3,"name":"Charlie","age":35,"active":true}


# Bad: inconsistent order, mixed types, missing fields
{"name":"Alice","id":1,"active":true}
{"id":"2","age":25,"name":"Bob"}
{"id":3,"active":"yes","name":"Charlie"}

Heeft een veld geen waarde, neem het dan op met de JSON-waarde null in plaats van de sleutel helemaal weg te laten. Dat vereenvoudigt de verdere verwerking, omdat elk record dezelfde sleutels bevat. Code die de data verwerkt, hoeft dan geen onderscheid te maken tussen "veld ontbreekt" en "veld is null".

Maak ontbrekende waarden expliciet
# Good: include all fields, use null for missing values
{"id":1,"name":"Alice","email":"[email protected]","phone":null}
{"id":2,"name":"Bob","email":null,"phone":"+1-555-0100"}


# Avoid: omitting keys for missing data
{"id":1,"name":"Alice","email":"[email protected]"}
{"id":2,"name":"Bob","phone":"+1-555-0100"}

Foutafhandeling

In de praktijk bevatten JSONL-bestanden vaak enkele ongeldige regels door problemen met tekencodering, onvolledig weggeschreven data of bugs eerder in de keten. Robuuste code vangt die fouten netjes op en loopt niet bij de eerste ongeldige regel vast.

Zet de parsebewerking voor elke regel in een try-catch-blok en log bij elke fout het regelnummer en de foutmelding. Zo kun je ongeldige regels overslaan en tegelijk vastleggen wat er misging. Verzamel ongeldige regels bij kritieke pipelines in een apart bestand, zodat je ze later kunt onderzoeken.

Parsefouten opvangen en regelnummers bijhouden
import json


def parse_jsonl_safe(path: str):
    """Parse JSONL with error tolerance."""
    valid, errors = [], []
    with open(path, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            try:
                valid.append(json.loads(line))
            except json.JSONDecodeError as e:
                errors.append({'line': line_num, 'error': str(e), 'raw': line})
    print(f'Parsed {len(valid)} records, {len(errors)} errors')
    return valid, errors

Voeg in datapipelines een validatiestap toe voordat de eigenlijke verwerking begint. Controleer of elk record de verwachte velden en datatypen bevat. Wijs afwijkende records af of zet ze apart. Zo voorkom je dat typefouten pas verderop in je pipeline optreden, waar ze lastiger te debuggen zijn.

Valideer vóór de verwerking
def validate_record(record: dict) -> list[str]:
    """Validate a JSONL record against expected schema."""
    issues = []
    required = ['id', 'name', 'timestamp']
    for field in required:
        if field not in record:
            issues.append(f'Missing required field: {field}')
    if 'id' in record and not isinstance(record['id'], int):
        issues.append(f'Field "id" should be int, got {type(record["id"]).__name__}')
    return issues


# Usage in pipeline
for record in parse_jsonl_safe('data.jsonl')[0]:
    issues = validate_record(record)
    if issues:
        log_warning(f'Record {record.get("id")}: {issues}')
    else:
        process(record)

Prestaties optimaliseren

In workflows voor data-engineering en machine learning kunnen JSONL-bestanden uitgroeien tot meerdere gigabytes. Met de juiste verwerkingsstrategie houd je het geheugengebruik beperkt en de verwerkingssnelheid hoog.

Laad nooit een volledig JSONL-bestand in één keer in het geheugen. Lees en verwerk steeds één regel of een batch regels. Zo blijft het geheugengebruik constant, ongeacht de bestandsgrootte. In Python verloopt iteratie over een bestand standaard regel voor regel. Node.js biedt hiervoor readline en stream-API’s.

Streamend verwerken
# Python: stream with constant memory
import json


count = 0
with open('large.jsonl', 'r', encoding='utf-8') as f:
    for line in f:  # One line at a time, not f.readlines()!
        record = json.loads(line)
        process(record)
        count += 1
print(f'Processed {count} records')

Bundel meerdere records in een batch wanneer je naar een database schrijft of API-aanroepen doet, in plaats van elk record afzonderlijk te verwerken. Dat vermindert de I/O-overhead en kan de verwerkingssnelheid 10-100x zo hoog maken. Voor de meeste toepassingen werkt een batchgrootte van 1.000 tot 10.000 records goed.

Records in batches verwerken
import json


def process_in_batches(path: str, batch_size: int = 5000):
    """Process JSONL records in batches for better throughput."""
    batch = []
    with open(path, 'r', encoding='utf-8') as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            batch.append(json.loads(line))
            if len(batch) >= batch_size:
                bulk_insert(batch)  # Send batch to database
                batch.clear()
    if batch:
        bulk_insert(batch)  # Flush remaining records

JSONL laat zich erg goed comprimeren, omdat opeenvolgende regels vaak dezelfde sleutels en vergelijkbare waarden bevatten. Gebruik gzip voor opslag en overdracht om bestanden 5-10x kleiner te maken. In de meeste programmeertalen kun je met gzip gecomprimeerde JSONL direct lezen, zonder die eerst op schijf uit te pakken.

Gebruik compressie voor opslag en overdracht
import gzip
import json


# Write compressed JSONL
with gzip.open('data.jsonl.gz', 'wt', encoding='utf-8') as f:
    for record in records:
        f.write(json.dumps(record, ensure_ascii=False) + '\n')


# Read compressed JSONL
with gzip.open('data.jsonl.gz', 'rt', encoding='utf-8') as f:
    for line in f:
        record = json.loads(line)
        process(record)

Veelvoorkomende fouten voorkomen

Dit zijn de problemen die we het vaakst tegenkomen wanneer gebruikers JSONL-bestanden met onze tools valideren. Ze veroorzaken allemaal parsefouten waarvan de oorzaak zonder de juiste aanpak lastig te achterhalen kan zijn.

JSON staat geen komma toe na het laatste element in een object of array. Dit is een van de meest voorkomende fouten, vooral bij ontwikkelaars die JavaScript gewend zijn, waar zulke trailing commas wel zijn toegestaan. Verwijder deze komma’s altijd uit je uitvoer.

Komma’s na het laatste element
# INVALID: trailing comma after last property
{"id": 1, "name": "Alice",}


# VALID: no trailing comma
{"id": 1, "name": "Alice"}


# INVALID: trailing comma in array
{"tags": ["admin", "user",]}


# VALID: no trailing comma in array
{"tags": ["admin", "user"]}

Een letterlijk regeleindeteken in een stringwaarde doorbreekt de regel dat elk record op één regel moet staan en maakt je JSONL-bestand ongeldig. Gebruik in JSON-strings altijd de escape-notatie \n, nooit een letterlijk regeleinde. De meeste JSON-serializers regelen dit automatisch, maar let hierop als je JSON-strings handmatig opbouwt.

Regeleinden in stringwaarden
# INVALID: raw newline inside a string value breaks JSONL
{"id": 1, "bio": "Line one
Line two"}


# VALID: escaped newline keeps everything on one line
{"id": 1, "bio": "Line one\nLine two"}


# Tip: json.dumps() in Python handles this automatically
import json
record = {"bio": "Line one\nLine two"}
print(json.dumps(record))
# Output: {"bio": "Line one\nLine two"}

Als je UTF-8 en Latin-1 of andere tekencoderingen in hetzelfde bestand door elkaar gebruikt, krijg je onleesbare tekens en parsefouten. Dit gebeurt vaak als je data uit verschillende bronnen aan een bestand toevoegt. Zet de data altijd om naar UTF-8 voordat je die wegschrijft. Ontvang je data met een onbekende tekencodering, bepaal die dan eerst met een library zoals chardet voordat je de data omzet.

Gemengde of onjuiste tekencodering
# Python: detect and convert encoding
import chardet


def normalize_to_utf8(input_path: str, output_path: str):
    """Detect encoding and convert to UTF-8."""
    with open(input_path, 'rb') as f:
        raw = f.read()
    detected = chardet.detect(raw)
    encoding = detected['encoding'] or 'utf-8'
    print(f'Detected encoding: {encoding}')
    text = raw.decode(encoding)
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(text)

Bestandsnamen en mapindeling

Met duidelijke bestandsnamen en een logische mapstructuur kun je JSONL-data makkelijker vinden, beheren en verwerken in geautomatiseerde pipelines.

Gebruik .jsonl als standaardbestandsextensie. Dit is de bekendste extensie voor JSON Lines-bestanden. Tools zoals de fine-tuning-API van OpenAI, BigQuery en de meeste dataplatforms verwachten deze extensie. De extensie .ndjson (Newline Delimited JSON) staat technisch voor hetzelfde formaat, maar onder een andere naam. Kies één conventie en houd die in je hele project aan.

De extensies .jsonl en .ndjson
# Recommended file naming conventions
data.jsonl              # Standard JSONL file
users_2026-02-14.jsonl  # Date-stamped export
train.jsonl             # ML training data
validation.jsonl        # ML validation split
events.jsonl.gz         # Compressed JSONL

Orden JSONL-bestanden op doel en datum. Houd ruwe invoerdata gescheiden van verwerkte uitvoer. Gebruik voor tijdreeksen of logdata een indeling in partities op datum, zodat je eenvoudig specifieke periodes kunt verwerken en oude data kunt opruimen.

Mapstructuur voor JSONL-projecten
project/
  data/
    raw/                  # Original unprocessed files
      events_2026-02-13.jsonl
      events_2026-02-14.jsonl
    processed/            # Cleaned and transformed
      events_clean.jsonl
    schemas/              # Schema documentation
      event_schema.json
  scripts/
    validate.py           # Validation script
    transform.py          # Transformation pipeline

Controleer nu je JSONL-bestanden

Valideer en formatteer JSONL-bestanden tot 1GB direct in je browser. Spoor opmaakfouten, schemaproblemen en problemen met tekencodering meteen op.

Veelgestelde vragen

Bronnen