Autor: Jerry Fan

Dobre praktyki pracy z JSONL

Kompleksowy przewodnik po tworzeniu poprawnych, niezawodnych i wydajnych plików JSONL. Poznaj zasady formatowania, projektowania schematów i obsługi błędów oraz techniki optymalizacji stosowane w środowiskach produkcyjnych.

Dlaczego warto stosować dobre praktyki w JSONL

JSONL (JSON Lines) tylko z pozoru jest prosty: jeden obiekt JSON w każdej linii, a między nimi znaki nowej linii. Ta prostota nie oznacza jednak, że nie można popełnić błędów. Niespójne schematy, problemy z kodowaniem, zbędne przecinki na końcu i znaki nowej linii wewnątrz wartości należą do najczęstszych przyczyn błędów parsowania w produkcyjnych procesach przetwarzania danych. Przestrzeganie jasno określonych zasad pozwala zapobiec tym problemom.

W tym przewodniku znajdziesz najważniejsze zasady niezawodnego zapisywania i odczytywania danych JSONL. Niezależnie od tego, czy tworzysz zbiory danych do uczenia maszynowego, przesyłasz strumieniowo logi aplikacji, czy wymieniasz dane między usługami, te praktyki pomogą Ci uniknąć trudnych do zauważenia błędów i wydajniej pracować z JSONL.

Zasady formatowania

Aby plik JSONL był poprawny, trzeba ściśle przestrzegać kilku zasad formatowania. Złamanie dowolnej z nich sprawi, że większość parserów odrzuci plik.

Każda linia pliku JSONL musi zawierać kompletną, samodzielną wartość JSON. Nigdy nie rozbijaj pojedynczego obiektu JSON na wiele linii. JSON sformatowany z wcięciami i podziałem na linie (pretty-print) nie jest poprawnym JSONL. Zawsze serializuj dane w zwartej postaci, bez wcięć i dodatkowych białych znaków między kluczami a wartościami.

Jeden obiekt JSON w każdej linii
# 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"
}

Pliki JSONL muszą być zapisane w kodowaniu UTF-8. Oczekuje go praktycznie każdy parser JSONL, narzędzie do przetwarzania strumieniowego i usługa chmurowa. Unikaj UTF-16, Latin-1 i innych kodowań. Jeśli dane źródłowe mają inne kodowanie, przekonwertuj je na UTF-8 przed zapisaniem w formacie JSONL.

Zawsze używaj kodowania 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');

Do oddzielania linii używaj pojedynczego znaku LF (line feed, \n). To standard w systemach Linux i macOS oraz w większości środowisk chmurowych. Unikaj stosowanej w Windows sekwencji CRLF (carriage return + line feed, \r\n), ponieważ może powodować problemy z parsowaniem. Większość współczesnych edytorów i narzędzi obsługuje to automatycznie, ale jeśli pracujesz na różnych platformach, sprawdź ustawienia.

Wybór znaków końca linii
# 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

Spójność schematu

JSONL nie narzuca schematu, ale zachowanie spójności rekordów znacznie ułatwia pracę z danymi. Niespójne schematy prowadzą do błędów w czasie wykonywania programu, nieoczekiwanych wartości null i nieudanych importów.

We wszystkich rekordach zachowuj te same nazwy i kolejność pól oraz typy wartości. JSON nie wymaga określonej kolejności pól, ale jej zachowanie poprawia czytelność i skuteczność kompresji. Nigdy nie używaj różnych typów dla tego samego pola — np. pole "price" nie powinno zawierać tekstu w jednych rekordach, a liczby w innych.

Spójna kolejność i typy pól
# 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"}

Jeśli pole nie ma wartości, zapisz je z wartością null zamiast całkowicie pomijać klucz. Upraszcza to dalsze przetwarzanie, ponieważ każdy rekord zawiera ten sam zestaw kluczy. Kod odczytujący dane nie musi rozróżniać sytuacji, w której pole nie istnieje, od tej, w której ma wartość null.

Jawnie oznaczaj brakujące wartości
# 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"}

Obsługa błędów

W praktyce pliki JSONL często zawierają niewielką liczbę niepoprawnych linii wskutek problemów z kodowaniem, przerwanego zapisu lub błędów w systemach źródłowych. Odporny na błędy kod odczytujący dane potrafi je obsłużyć, zamiast przerywać działanie przy pierwszej błędnej linii.

Umieść parsowanie każdej linii w bloku try-catch, a w razie błędu zapisz w logach numer linii i komunikat błędu. Dzięki temu możesz pomijać niepoprawne linie i jednocześnie zachować informacje o problemach. W krytycznych procesach przetwarzania danych zapisuj błędne linie w osobnym pliku do późniejszej analizy.

Parsowanie z obsługą błędów i numerami linii
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

Dodaj etap walidacji przed główną częścią procesu przetwarzania danych. Sprawdź, czy każdy rekord zawiera oczekiwane pola i czy mają one właściwe typy. Rekordy niezgodne ze schematem odrzucaj lub odkładaj do osobnej analizy. Pozwoli to uniknąć błędów typów na dalszych etapach przetwarzania, gdzie trudniej znaleźć ich przyczynę.

Waliduj dane przed przetwarzaniem
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)

Optymalizacja wydajności

W inżynierii danych i uczeniu maszynowym pliki JSONL mogą osiągać rozmiary liczone w gigabajtach. Odpowiednia strategia przetwarzania pozwala ograniczyć zużycie pamięci i zachować wysoką przepustowość.

Nigdy nie wczytuj całego pliku JSONL do pamięci naraz. Odczytuj i przetwarzaj po jednej linii lub po jednej partii linii. Dzięki temu zużycie pamięci pozostaje stałe niezależnie od rozmiaru pliku. Iteracja po pliku w Pythonie domyślnie odczytuje kolejne linie, a w Node.js służą do tego API readline i stream.

Przetwarzanie strumieniowe
# 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')

Przy zapisie do bazy danych lub wywoływaniu API grupuj rekordy w partie zamiast przetwarzać je pojedynczo. Zmniejsza to narzut operacji I/O i może zwiększyć przepustowość 10-100 razy. W większości przypadków sprawdzają się partie liczące od 1000 do 10000 rekordów.

Przetwarzanie partiami
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

Pliki JSONL bardzo dobrze się kompresują, ponieważ sąsiadujące linie często zawierają te same klucze i podobne wartości. Przy przechowywaniu i przesyłaniu używaj gzip, aby zmniejszyć rozmiar plików 5-10 razy. W większości języków można odczytywać pliki JSONL skompresowane za pomocą gzip bezpośrednio, bez wcześniejszego rozpakowywania na dysk.

Kompresuj pliki do przechowywania i przesyłania
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)

Typowe błędy, których warto unikać

Oto problemy, które najczęściej obserwujemy podczas walidacji plików JSONL przez użytkowników naszych narzędzi. Każdy z nich powoduje błędy parsowania, których przyczynę trudno ustalić bez odpowiedniego podejścia.

JSON nie dopuszcza przecinka po ostatnim elemencie obiektu lub tablicy. To jeden z najczęstszych błędów, zwłaszcza u programistów przyzwyczajonych do JavaScript, gdzie takie przecinki są dozwolone. Zawsze usuwaj je z danych wyjściowych.

Przecinki po ostatnim elemencie
# 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"]}

Dosłowny znak nowej linii w wartości tekstowej łamie zasadę jednego rekordu na linię i sprawia, że plik JSONL jest niepoprawny. W ciągach JSON zawsze zapisuj go jako sekwencję \n, nigdy jako rzeczywiste przejście do nowej linii. Większość serializatorów JSON robi to automatycznie, ale przy ręcznym tworzeniu tekstu JSON trzeba na to uważać.

Znaki nowej linii w wartościach tekstowych
# 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"}

Mieszanie UTF-8 z Latin-1 lub innymi kodowaniami w jednym pliku powoduje nieprawidłowe wyświetlanie znaków i błędy parsowania. Często zdarza się to przy dopisywaniu danych z różnych źródeł. Przed zapisem zawsze konwertuj dane do UTF-8. Jeśli otrzymasz dane w nieznanym kodowaniu, przed konwersją wykryj je za pomocą biblioteki takiej jak chardet.

Różne lub nieprawidłowe kodowania
# 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)

Nazewnictwo i organizacja plików

Przemyślane nazwy plików i struktura katalogów ułatwiają odnajdywanie danych JSONL, zarządzanie nimi i ich przetwarzanie w zautomatyzowanych procesach.

Domyślnie używaj rozszerzenia .jsonl. Jest ono najbardziej rozpoznawalnym rozszerzeniem plików JSON Lines i oczekują go takie narzędzia jak API do fine-tuningu OpenAI, BigQuery oraz większość platform do pracy z danymi. Rozszerzenie .ndjson (Newline Delimited JSON) oznacza technicznie ten sam format pod inną nazwą. Wybierz jedną konwencję i stosuj ją konsekwentnie w całym projekcie.

Rozszerzenia .jsonl i .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

Organizuj pliki JSONL według przeznaczenia i daty. Oddzielaj surowe dane wejściowe od przetworzonych danych wyjściowych. Szeregi czasowe i logi dziel na partycje według dat, aby łatwo przetwarzać dane z wybranych okresów i usuwać stare dane.

Struktura katalogów w projektach korzystających z JSONL
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

Sprawdź swoje pliki JSONL już teraz

Waliduj i formatuj pliki JSONL o rozmiarze do 1GB bezpośrednio w przeglądarce. Błyskawicznie wykrywaj błędy formatowania oraz problemy ze schematem i kodowaniem.

Najczęściej zadawane pytania

Źródła