Autor: Jerry Fan

Walidacja JSONL przy użyciu schematu: zadbaj o jakość danych

Kompleksowy przewodnik po walidacji plików JSONL za pomocą JSON Schema. Dowiedz się, jak definiować schematy, walidować rekordy w Pythonie i Node.js, automatyzować kontrole w pipeline’ach CI/CD oraz diagnozować typowe błędy walidacji.

Dlaczego warto walidować pliki JSONL za pomocą schematu

Pliki JSONL (JSON Lines) są powszechnie używane do zbierania logów, przechowywania zbiorów danych do uczenia maszynowego, przetwarzania wsadowego w API oraz w pipeline’ach danych. Każda linia jest niezależnym obiektem JSON, więc format nie ma wbudowanego mechanizmu, który wymuszałby spójną strukturę wszystkich rekordów. Wystarczy jedna niepoprawna linia, brak wymaganego pola lub nieoczekiwany typ danych, by bez wyraźnego sygnału błędu zakłócić dalsze przetwarzanie, przerwać trening modelu albo spowodować błąd zadania wsadowego API w połowie jego wykonania.

Walidacja za pomocą schematu rozwiązuje ten problem: określa formalny kontrakt, który musi spełniać każdy rekord. JSON Schema to branżowy standard opisu struktury, typów i ograniczeń danych JSON. Jeśli sprawdzisz każdą linię pliku JSONL pod kątem zgodności z JSON Schema, zanim trafi do pipeline’u, wcześnie wykryjesz błędy, skrócisz czas debugowania i zapewnisz jakość danych nawet przy dużej skali. Ten przewodnik przeprowadzi Cię przez cały proces — od napisania pierwszego schematu po włączenie walidacji do zautomatyzowanych procesów CI/CD.

Podstawy JSON Schema w pracy z JSONL

JSON Schema to język deklaratywny, który pozwala opisać oczekiwaną strukturę obiektu JSON. Określasz w nim między innymi wymagane pola, ich typy danych, dopuszczalne zakresy wartości i wzorce dla ciągów znaków. Przy walidacji JSONL ten sam schemat służy do sprawdzenia każdej linii pliku. Dzięki temu wszystkie rekordy mają spójną strukturę, niezbędną do niezawodnego przetwarzania danych.

Poniżej znajdziesz przykładowy schemat JSON Schema dla rekordu zdarzenia użytkownika. Wymagane pola to id (liczba całkowita), event (ciąg znaków z określonego zbioru) i timestamp (format ISO 8601). Obiekt metadata jest opcjonalny. Ustawienie additionalProperties na false powoduje odrzucenie wszystkich nieoczekiwanych kluczy.

Zdefiniuj schemat JSON Schema
{
  "$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
}

Oto plik JSONL z rekordami zgodnymi z powyższym schematem. Każda linia zawiera samodzielny obiekt JSON opisujący jedno zdarzenie użytkownika. Zwróć uwagę, że opcjonalne pole metadata występuje tylko w niektórych liniach — zarówno jego obecność, jak i brak są zgodne ze schematem.

Przykładowe dane JSONL
{"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"}

Walidacja plików JSONL: Python, Node.js i CLI

Do sprawdzania zgodności danych JSONL z JSON Schema możesz użyć kilku sprawdzonych narzędzi. Wybór zależy przede wszystkim od technologii, z których już korzystasz. Programiści Pythona zazwyczaj używają biblioteki jsonschema, programiści JavaScriptu sięgają po Ajv, a zespoły preferujące skrypty powłoki mogą skorzystać z walidatorów uruchamianych z wiersza poleceń. Poniżej znajdziesz przykłady wszystkich trzech podejść.

jsonschema to najpopularniejszy pakiet Pythona do walidacji danych za pomocą JSON Schema. Zainstaluj go poleceniem pip install jsonschema. Poniższy skrypt czyta plik JSONL linia po linii, waliduje każdy rekord i zbiera wszystkie błędy wraz z numerami linii, co ułatwia debugowanie.

Python i biblioteka 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) to najszybszy walidator JSON Schema dla JavaScriptu. Zainstaluj go poleceniem npm install ajv ajv-formats. Pakiet ajv-formats dodaje obsługę formatów takich jak date-time, wskazywanych słowem kluczowym format. Skrypt odczytuje plik JSONL strumieniowo, linia po linii, dzięki czemu zużywa niewiele pamięci.

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

Do szybkich, jednorazowych kontroli lub automatyzacji w powłoce możesz połączyć jq i ajv-cli. W poniższym przykładzie plik JSONL jest dzielony na pojedyncze obiekty JSON, a każdy z nich jest sprawdzany pod kątem zgodności ze schematem. To przydatne rozwiązanie, gdy nie chcesz pisać własnego skryptu.

Walidacja z wiersza poleceń
# 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

Automatyzacja walidacji w pipeline’ach CI/CD

Ręczna walidacja sprawdza się przy małych zbiorach danych, ale procesy produkcyjne wymagają automatyzacji. Gdy włączysz walidację JSONL za pomocą schematu do pipeline’u CI/CD, każda zmiana danych zostanie sprawdzona przed wdrożeniem na produkcję. W ten sposób zapobiegniesz sytuacjom, w których błędne dane trafiają do hurtowni, zakłócają trening modelu lub powodują błędy zadań wsadowych API. Poniższy workflow GitHub Actions waliduje pliki JSONL przy każdym pushu i pull requeście.

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

Ten workflow uruchamia się tylko po zmianie plików JSONL w katalogu data, dzięki czemu CI działa szybko. Skrypt wczytuje schemat tylko raz i sprawdza wszystkie pliki JSONL znalezione rekurencyjnie w tym katalogu i jego podkatalogach. Jeśli choć jeden rekord nie przejdzie walidacji, workflow kończy się kodem różnym od zera, blokując scalenie zmian. Możesz rozbudować to rozwiązanie o osobne schematy dla różnych typów plików, powiadomienia na Slacku w razie błędu lub zapisywanie raportów walidacji jako artefaktów procesu budowania.

Typowe błędy walidacji i sposoby ich naprawy

Pierwsza walidacja istniejącego zbioru danych JSONL za pomocą schematu często ujawnia ukryte problemy z jakością danych. Oto trzy najczęstsze błędy walidacji i sposoby ich naprawy.

Niezgodność typów

Niezgodność typów występuje, gdy wartość pola ma inny typ niż wymagany. Najczęściej dotyczy to liczbowych identyfikatorów zapisanych jako ciągi znaków, na przykład po eksporcie danych z arkuszy kalkulacyjnych lub plików CSV. Aby rozwiązać ten problem, przekonwertuj wartość na właściwy typ podczas procesu ETL. Jeśli oba typy są poprawne, zmień schemat tak, by dopuszczał więcej niż jeden typ.

Przykład: ID jako ciąg znaków zamiast liczby całkowitej
// 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)

Brak wymaganych pól

Ten błąd oznacza, że w rekordzie brakuje właściwości wymienionej w tablicy required schematu. Zwykle dzieje się tak, gdy systemy źródłowe zmieniają format danych wyjściowych lub gdy pola opcjonalne zostają omyłkowo pominięte. Dodaj obsługę wartości domyślnych w pipeline’ie danych albo zmień schemat tak, by pole było opcjonalne, jeśli rzeczywiście nie zawsze występuje.

Przykład: brak pola timestamp
// 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"]

Nieoczekiwane dodatkowe właściwości

Jeśli ustawisz additionalProperties na false, każde pole niewymienione w properties spowoduje błąd walidacji. To restrykcyjne podejście, ale pomaga wykrywać literówki i wycieki danych. Jeśli chcesz dopuszczać dodatkowe pola, ustaw additionalProperties na true lub określ wzorzec dozwolonych nazw właściwości za pomocą patternProperties.

Przykład: nieznane pole w rekordzie
// 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

Sprawdź swoje pliki JSONL już teraz

Wczytaj plik JSONL i od razu sprawdź, czy zawiera błędy składni, struktury lub formatowania. Bez wysyłania danych na serwer, ze 100% prywatności.

Najczęściej zadawane pytania

Źródła