Von Jerry Fan

JSONL-Schema-Validierung: Datenqualität sicherstellen

Eine ausführliche Anleitung zur Validierung von JSONL-Dateien mit JSON Schema. Erfahren Sie, wie Sie Schemas definieren, Datensätze mit Python und Node.js validieren, Prüfungen in CI/CD-Pipelines automatisieren und häufige Validierungsfehler aufspüren.

Warum JSONL-Dateien eine Schema-Validierung brauchen

JSONL-Dateien (JSON Lines) werden häufig für die Erfassung von Logs, Machine-Learning-Datensätze, die Batch-Verarbeitung von API-Anfragen und Datenpipelines eingesetzt. Jede Zeile ist ein eigenständiges JSON-Objekt. Das Format selbst bietet daher keinen Mechanismus, der eine einheitliche Struktur aller Datensätze erzwingt. Schon eine einzige fehlerhaft formatierte Zeile, ein fehlendes Pflichtfeld oder ein unerwarteter Datentyp kann unbemerkt zu Fehlern in der nachgelagerten Verarbeitung führen, das Modelltraining zum Scheitern bringen oder API-Batch-Jobs mitten in der Ausführung abbrechen lassen.

Die Schema-Validierung löst dieses Problem mit einer verbindlichen Definition, die jeder Datensatz erfüllen muss. JSON Schema ist der Industriestandard, um die Struktur, Datentypen und Einschränkungen von JSON-Daten zu beschreiben. Wenn Sie jede Zeile einer JSONL-Datei anhand eines JSON Schemas validieren, bevor die Daten in Ihre Pipeline gelangen, erkennen Sie Fehler frühzeitig, sparen Zeit beim Debugging und sichern die Datenqualität auch bei großen Datenmengen. Diese Anleitung führt Sie durch den gesamten Prozess: vom ersten eigenen Schema bis zur Einbindung der Validierung in automatisierte CI/CD-Workflows.

Grundlagen von JSON Schema für JSONL

JSON Schema ist eine deklarative Sprache, mit der Sie die erwartete Struktur eines JSON-Objekts beschreiben. Sie legen fest, welche Felder erforderlich sind, welche Datentypen sie haben müssen, welche Wertebereiche und Muster für Strings zulässig sind und vieles mehr. Bei der JSONL-Validierung wird jede einzelne Zeile der Datei anhand desselben Schemas geprüft. So stellen Sie sicher, dass alle Datensätze eine einheitliche Struktur haben – eine wesentliche Voraussetzung für eine zuverlässige Datenverarbeitung.

Das folgende JSON Schema beschreibt einen Datensatz für ein Benutzerereignis. Pflichtfelder sind id (Ganzzahl), event (String aus einer festgelegten Wertemenge) und timestamp (im ISO 8601-Format). Zusätzlich ist ein optionales metadata-Objekt vorgesehen. additionalProperties ist auf false gesetzt, damit unerwartete Schlüssel abgelehnt werden.

Ein JSON Schema definieren
{
  "$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
}

Die Datensätze der folgenden JSONL-Datei entsprechen dem oben definierten Schema. Jede Zeile enthält ein eigenständiges JSON-Objekt, das ein Benutzerereignis darstellt. Das optionale Feld metadata ist in einigen Zeilen vorhanden und fehlt in anderen. Beides ist nach dem Schema zulässig.

JSONL-Beispieldaten
{"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-Dateien validieren: mit Python, Node.js und der Kommandozeile

Für die Validierung von JSONL anhand eines JSON Schemas gibt es mehrere bewährte Tools. Welches sich am besten eignet, hängt von Ihrem bestehenden Stack ab. In Python kommt meist die Bibliothek jsonschema zum Einsatz, in JavaScript Ajv. Teams, die mit Shell-Skripten arbeiten, können Validatoren für die Kommandozeile verwenden. Im Folgenden sehen Sie alle drei Ansätze.

Die Bibliothek jsonschema ist das beliebteste Python-Paket für die Validierung mit JSON Schema. Installieren Sie es mit pip install jsonschema. Das folgende Skript liest eine JSONL-Datei zeilenweise ein, validiert jeden Datensatz und sammelt alle Fehler samt Zeilennummern. Das erleichtert die Fehlersuche.

Python mit 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) ist der schnellste JSON-Schema-Validator für JavaScript. Installieren Sie ihn mit npm install ajv ajv-formats. Das Paket ajv-formats ergänzt die Unterstützung für Formatangaben wie date-time. Das folgende Skript verarbeitet die JSONL-Datei zeilenweise als Stream und hält so den Speicherverbrauch gering.

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

Für schnelle Einzelprüfungen oder Workflows mit Shell-Skripten können Sie jq und ajv-cli kombinieren. Der folgende Ansatz zerlegt die JSONL-Datei in einzelne JSON-Objekte und validiert jedes davon anhand des Schemas. Das ist praktisch, wenn Sie kein eigenes Skript schreiben möchten.

Validierung auf der Kommandozeile
# 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

Validierung in CI/CD-Pipelines automatisieren

Bei kleinen Datenbeständen reicht eine manuelle Validierung oft aus. Für produktive Workflows ist jedoch eine Automatisierung nötig. Wenn Sie die JSONL-Schema-Validierung in Ihre CI/CD-Pipeline einbinden, wird jede Datenänderung geprüft, bevor sie in die Produktionsumgebung gelangt. So verhindern Sie, dass fehlerhafte Daten in Ihr Data Warehouse gelangen, das Modelltraining zum Scheitern bringen oder Fehler in API-Batch-Jobs verursachen. Der folgende GitHub-Actions-Workflow validiert JSONL-Dateien bei jedem Push und Pull Request.

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!')
          "

Dieser Workflow wird nur ausgelöst, wenn sich JSONL-Dateien im Verzeichnis data ändern. So bleiben die CI-Läufe schnell. Das Validierungsskript lädt das Schema einmal und prüft alle JSONL-Dateien, die es bei der rekursiven Suche findet. Sobald ein Datensatz die Validierung nicht besteht, endet der Workflow mit einem Exit-Code ungleich null und blockiert damit den Merge. Sie können diesen Ansatz erweitern: etwa mit mehreren Schemas für unterschiedliche Dateitypen, Slack-Benachrichtigungen bei Fehlern oder Validierungsberichten, die als Build-Artefakte hochgeladen werden.

Häufige Validierungsfehler und ihre Behebung

Wenn Sie die Schema-Validierung für einen bestehenden JSONL-Datenbestand zum ersten Mal aktivieren, kommen oft bisher unbemerkte Probleme mit der Datenqualität ans Licht. Die folgenden drei Validierungsfehler treten besonders häufig auf. Hier erfahren Sie, wie Sie sie beheben.

Falscher Datentyp

Ein Typfehler liegt vor, wenn der Wert eines Feldes den falschen Datentyp hat. Besonders häufig werden numerische IDs als Strings gespeichert, etwa beim Export aus Tabellenkalkulationen oder CSV-Dateien. Wandeln Sie den Wert im ETL-Prozess in den richtigen Typ um. Wenn beide Typen zulässig sind, können Sie stattdessen das Schema so anpassen, dass es mehrere Typen akzeptiert.

Beispiel: ID als String statt als Ganzzahl
// 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)

Fehlende Pflichtfelder

Dieser Fehler bedeutet, dass einem Datensatz eine Eigenschaft fehlt, die im required-Array des Schemas aufgeführt ist. Das passiert häufig, wenn vorgelagerte Systeme ihr Ausgabeformat ändern oder optionale Felder versehentlich weggelassen werden. Ergänzen Sie in Ihrer Datenpipeline eine Behandlung für Standardwerte. Falls das Feld tatsächlich nicht immer vorhanden ist, können Sie es stattdessen im Schema als optional definieren.

Beispiel: Das Feld timestamp fehlt
// 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"]

Unerwartete zusätzliche Eigenschaften

Wenn additionalProperties in Ihrem Schema auf false gesetzt ist, löst jedes Feld einen Validierungsfehler aus, das nicht ausdrücklich in properties aufgeführt ist. Diese strikte Prüfung hilft, Tippfehler und Datenlecks zu erkennen. Wenn Sie zusätzliche Felder bewusst zulassen möchten, setzen Sie additionalProperties auf true oder legen Sie mit patternProperties ein Muster für zulässige Eigenschaftsnamen fest.

Beispiel: Unbekanntes Feld im Datensatz
// 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

Jetzt Ihre JSONL-Dateien validieren

Laden Sie Ihre JSONL-Datei hoch und prüfen Sie sie sofort auf Syntaxfehler, Strukturprobleme und Formatierungsfehler. Kein Upload auf einen Server, 100 % privat.

Häufig gestellte Fragen

Quellen