Autor: Jerry Fan

Czym jest JSONL? Pełny przewodnik po formacie JSON Lines

Wszystko, co musisz wiedzieć o JSON Lines — składnia, przykłady, zastosowania i dobre praktyki.

Czym jest JSONL?

JSONL (JSON Lines), znany też jako Newline Delimited JSON (NDJSON), to tekstowy format danych, w którym każda linia zawiera poprawną wartość JSON, a poszczególne linie rozdziela znak nowej linii. Standardowy JSON zapisuje dane w jednej tablicy lub jednym obiekcie, natomiast JSONL przechowuje po jednym rekordzie w każdej linii.

Dzięki tej prostej strukturze JSONL świetnie nadaje się do strumieniowego przesyłania danych, zapisywania logów i przetwarzania dużych zbiorów danych — każdą linię można odczytać, sparsować i przetworzyć niezależnie, bez wczytywania całego pliku do pamięci.

Format spopularyzowały narzędzia i platformy przetwarzające ogromne ilości danych, m.in. OpenAI (zbiory danych do fine-tuningu), BigQuery, Apache Spark oraz systemy zarządzania logami.

Zasady składni JSONL

Format JSONL opiera się na kilku prostych zasadach:

  • Każda linia musi zawierać poprawną wartość JSON (obiekt, tablicę, łańcuch znaków, liczbę, wartość logiczną lub null)
  • Linie rozdziela się znakami nowej linii (\n)
  • Między liniami nie umieszcza się przecinków ani dodatkowych separatorów
  • Pliki muszą być zapisane w kodowaniu UTF-8
  • Znak nowej linii na końcu pliku jest opcjonalny
  • Większość parserów ignoruje puste linie
Poprawny plik JSONL
{"name":"Alice","age":30,"city":"New York"}
{"name":"Bob","age":25,"city":"London"}
{"name":"Charlie","age":35,"city":"Tokyo"}

Uwaga: każda linia zawiera kompletny, niezależny obiekt JSON. Między liniami nie ma przecinków, a całość nie jest ujęta w tablicę.

Przykłady JSONL

Proste obiekty
{"id":1,"name":"Alice","email":"[email protected]"}
{"id":2,"name":"Bob","email":"[email protected]"}
{"id":3,"name":"Charlie","email":"[email protected]"}
Zagnieżdżone obiekty
{"user":{"name":"Alice","age":30},"scores":[95,87,92]}
{"user":{"name":"Bob","age":25},"scores":[88,91,76]}

Wartości w poszczególnych liniach JSONL nie muszą być tego samego typu — wystarczy, że każda linia zawiera poprawny JSON:

Różne typy danych
{"event":"login","user":"alice","timestamp":"2026-01-15T10:30:00Z"}
{"event":"purchase","user":"alice","amount":29.99,"items":["book","pen"]}
{"event":"logout","user":"alice","timestamp":"2026-01-15T11:45:00Z"}

Jednym z najpopularniejszych zastosowań JSONL są zbiory danych do fine-tuningu modeli OpenAI:

PopularFormat danych do fine-tuningu w OpenAI
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is JSONL?"},{"role":"assistant","content":"JSONL is a text format where each line is a valid JSON value."}]}
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"How do I read a JSONL file?"},{"role":"assistant","content":"Read the file line by line, parsing each line as JSON."}]}

Jak odczytywać pliki JSONL

Pliki JSONL możesz odczytywać dowolnym narzędziem, które obsługuje przetwarzanie tekstu linia po linii. Oto najczęściej używane sposoby:

Do przeglądania zawartości plików JSONL użyj standardowych narzędzi uniksowych:

Wiersz poleceń
# View first 5 lines
head -n 5 data.jsonl


# Count total lines (records)
wc -l data.jsonl


# Pretty-print each line with jq
cat data.jsonl | jq .


# Filter by field value
cat data.jsonl | jq 'select(.age > 30)'

Wbudowany w Pythona moduł json dobrze nadaje się do obsługi JSONL:

Python
import json


with open('data.jsonl', 'r') as f:
    for line in f:
        record = json.loads(line)
        print(record['name'])

Tak odczytasz plik JSONL linia po linii w Node.js:

JavaScript / Node.js
import { createReadStream } from 'fs';
import { createInterface } from 'readline';


const rl = createInterface({
  input: createReadStream('data.jsonl')
});


for await (const line of rl) {
  const record = JSON.parse(line);
  console.log(record.name);
}

Przeglądarka JSONL online

Jeśli wolisz przeglądać dane w interfejsie graficznym, skorzystaj z jsonl.co. Otworzysz tam i przejrzysz pliki JSONL o rozmiarze do 1GB — bez wysyłania plików na serwer, wszystko działa w Twojej przeglądarce.

Jak tworzyć pliki JSONL

Aby utworzyć plik JSONL, wystarczy zapisać po jednej wartości JSON w każdej linii.

Python
import json


records = [
    {"name": "Alice", "age": 30},
    {"name": "Bob", "age": 25},
    {"name": "Charlie", "age": 35},
]


with open('output.jsonl', 'w') as f:
    for record in records:
        f.write(json.dumps(record) + '\n')
JavaScript / Node.js
import { writeFileSync } from 'fs';


const records = [
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 },
  { name: 'Charlie', age: 35 },
];


const jsonl = records
  .map(r => JSON.stringify(r))
  .join('\n');


writeFileSync('output.jsonl', jsonl + '\n');

Czy w JSONL można dodawać komentarze?

Nie. Specyfikacja JSONL nie przewiduje komentarzy. Każda linia pliku JSONL musi zawierać poprawną wartość JSON, a sam JSON nie ma składni komentarzy.

Jeśli chcesz dołączyć do danych metadane lub adnotacje, możesz skorzystać z jednego z typowych rozwiązań:

  • 1Dodaj do obiektów JSON pole z metadanymi: {"_comment": "dane testowe", "name": "Alice"}
  • 2Zapisz metadane w osobnym pliku obok pliku JSONL
  • 3Umieść metadane w pierwszej linii pliku: {"_meta": {"version": "1.0", "created": "2026-01-15"}}

Pamiętaj, że pola z „komentarzami” będą parsowane jak zwykłe dane. Aplikacje odczytujące plik JSONL powinny być przygotowane do ignorowania pól z metadanymi.

JSONL vs JSON

Główna różnica tkwi w strukturze. JSON zapisuje całość jako jedną wartość, a JSONL przechowuje po jednej wartości w każdej linii.

JSONStandardowy JSON
[
  {"name": "Alice", "age": 30},
  {"name": "Bob", "age": 25}
]
JSONLJSONL (JSON Lines)
{"name":"Alice","age":30}
{"name":"Bob","age":25}
  • Aby sparsować JSON, trzeba wczytać go w całości do pamięci; JSONL można odczytywać linia po linii
  • W JSON elementy rozdziela się przecinkami; w JSONL służą do tego znaki nowej linii
  • JSON lepiej sprawdza się w plikach konfiguracyjnych i API; JSONL — w dużych zbiorach danych i przetwarzaniu strumieniowym
  • Dopisanie danych do JSON wymaga ponownego zapisania całego pliku; w JSONL wystarczy dopisać nową linię

Szczegóły znajdziesz w naszym pełnym porównaniu: JSON vs JSONL guide.

Typowe zastosowania

Uczenie maszynowe i AI

Najpopularniejsze

JSONL to standardowy format danych treningowych w uczeniu maszynowym. OpenAI, Hugging Face i inne platformy AI używają go do zbiorów danych do fine-tuningu, ponieważ każdy przykład treningowy zajmuje osobną, niezależną linię. Ułatwia to wydajne mieszanie kolejności przykładów, próbkowanie i przesyłanie strumieniowe.

Pliki logów i strumienie zdarzeń

JSONL

Systemy zapisujące logi strukturalne (stos ELK, Datadog, CloudWatch) generują logi w formacie JSONL. Każdy wpis zajmuje jedną linię JSON, co ułatwia dopisywanie kolejnych wpisów i przetwarzanie logów w czasie rzeczywistym.

Przetwarzanie dużych zbiorów danych

JSONL

Narzędzia takie jak Apache Spark, BigQuery i AWS Athena mają wbudowaną obsługę JSONL. Zapis danych linia po linii umożliwia równoległe przetwarzanie w systemach rozproszonych — każdy worker może niezależnie przetwarzać przydzieloną mu grupę linii.

Strumieniowe API

JSONL

API zwracające duże zbiory wyników często przesyłają je strumieniowo w formacie JSONL. Klient może zacząć przetwarzać wyniki na bieżąco, gdy tylko je otrzyma, bez czekania na całą odpowiedź.

Rozszerzenia plików JSONL

Pliki JSONL najczęściej mają następujące rozszerzenia:

.jsonlStandardowe i najczęściej używane rozszerzenie plików JSONL
.ndjsonNewline Delimited JSON — pod względem technicznym ten sam format, tylko pod inną nazwą
.jsonNiektóre narzędzia zapisują JSONL w plikach z rozszerzeniem .json, co może być mylące

Pliki z każdym z tych trzech rozszerzeń zawierają dane w tym samym formacie — po jednej wartości JSON w każdej linii. Typ MIME dla JSONL to application/jsonl lub application/x-ndjson.

Wypróbuj naszą przeglądarkę JSONL

Otwieraj, przeglądaj i edytuj pliki JSONL o rozmiarze do 1GB — bezpośrednio w przeglądarce. Bez wysyłania plików na serwer, z zachowaniem 100% prywatności.

Najczęściej zadawane pytania

Źródła