- Strona główna
- Przewodnik
- JSONL a NDJSON: czym się różnią?
JSONL a NDJSON: czym się różnią?
Szczegółowe porównanie JSONL (JSON Lines) i NDJSON (Newline Delimited JSON) — dwóch nazw niemal tego samego formatu, między którymi istnieją drobne różnice warte poznania.
JSONL a NDJSON — szybkie porównanie
| Cecha | JSONL (JSON Lines) | NDJSON |
|---|---|---|
| Pełna nazwa | JSON Lines | Newline Delimited JSON |
| Rozszerzenie pliku | .jsonl | .ndjson |
| Specyfikacja | jsonlines.org (nieformalna) | github.com/ndjson/ndjson-spec (nieformalna specyfikacja) |
| Pochodzenie | Konwencja przyjęta przez społeczność, spopularyzowana przez narzędzia do data science | Format zaproponowany przez Chrisa Olaha, Thorstena Balla i innych |
| Separator linii | \n (znak nowej linii) | \n (znak nowej linii) |
| Typ MIME | application/jsonl (nieoficjalny) | application/x-ndjson |
| Obsługa strumieniowania | Tak, linia po linii | Tak, linia po linii |
| Zastosowanie | OpenAI, Hugging Face, ekosystem ML/AI | Elasticsearch, Apache Spark, inżynieria danych |
Czym jest JSONL (JSON Lines)?
JSONL to skrót od JSON Lines. Jest to tekstowy format danych, w którym każda linia zawiera jedną poprawną wartość JSON, a poszczególne linie oddziela znak nowej linii (\n). Format spopularyzowały społeczności zajmujące się uczeniem maszynowym i data science. Jego nieformalną definicję znajdziesz na jsonlines.org.
Pliki JSONL mają rozszerzenie .jsonl. Format stał się standardem zapisu danych treningowych dla AI i ML — OpenAI wymaga plików .jsonl do fine-tuningu, a zbiory danych Hugging Face często korzystają z formatu JSON Lines.
{"id": 1, "text": "Hello world", "label": "greeting"}
{"id": 2, "text": "How are you?", "label": "question"}
{"id": 3, "text": "Goodbye", "label": "farewell"}Czym jest NDJSON (Newline Delimited JSON)?
NDJSON, czyli Newline Delimited JSON, to format danych, w którym każda linia zawiera poprawną wartość JSON, a poszczególne linie oddziela znak nowej linii. Specyfikacja jest dostępna na github.com/ndjson/ndjson-spec. Powstała, by nadać bardziej uporządkowaną postać standardowi zapisu danych JSON rozdzielanych znakami nowej linii.
Pliki NDJSON mają rozszerzenie .ndjson i zarejestrowany typ MIME application/x-ndjson. Format jest powszechnie stosowany w inżynierii danych, przetwarzaniu logów i aplikacjach strumieniowych — korzystają z niego Elasticsearch, Apache Spark i liczne API przesyłające dane strumieniowo przez HTTP.
{"id": 1, "text": "Hello world", "label": "greeting"}
{"id": 2, "text": "How are you?", "label": "question"}
{"id": 3, "text": "Goodbye", "label": "farewell"}Czy JSONL i NDJSON to ten sam format?
W praktyce tak — JSONL i NDJSON działają identycznie. W obu formatach każda linia zawiera jedną wartość JSON, a linie oddziela znak nowej linii (\n). Pliki .jsonl i .ndjson zawierające te same dane można stosować zamiennie. Każde narzędzie, które odczytuje jeden z tych formatów, odczyta też drugi.
Różnice sprowadzają się do nazewnictwa, popularności w poszczególnych społecznościach i konwencji dotyczących metadanych. JSONL (JSON Lines) wywodzi się ze środowiska data science i uczenia maszynowego, a NDJSON (Newline Delimited JSON) został sformalizowany przez społeczność zajmującą się inżynierią danych i strumieniowaniem w aplikacjach webowych. To jak angielskie „movie” i „film” — znaczą to samo, ale różne środowiska preferują różne nazwy.
Najistotniejsze różnice to rozszerzenie pliku (.jsonl lub .ndjson) i typ MIME. Typ MIME formatu NDJSON (application/x-ndjson) jest szerzej rozpoznawany i stosowany przy strumieniowaniu przez HTTP, natomiast pliki JSONL są standardem w pracy z AI/ML. Przy wyborze kieruj się konwencją przyjętą w swoim ekosystemie.
Najważniejsze różnice między JSONL a NDJSON
1. Specyfikacja i źródło definicji
Format opisuje zwięzła, nieformalna specyfikacja na jsonlines.org. Zasady są proste: każda linia zawiera poprawną wartość JSON, linie oddziela znak '\n', a zalecanym kodowaniem jest UTF-8.
Format opisuje nieco bardziej formalna specyfikacja na github.com/ndjson/ndjson-spec. Wprost wymaga ona, by każda linia zawierała poprawną wartość JSON, a separatorem linii był znak '\n' (nie '\r\n'). Zaleca też znak nowej linii na końcu pliku.
2. Rozszerzenie pliku
Pliki mają rozszerzenie .jsonl. Jest ono standardem dla plików do fine-tuningu w OpenAI, zbiorów danych Hugging Face i większości narzędzi ML/AI. GitHub i VS Code rozpoznają pliki .jsonl i podświetlają ich składnię.
Pliki mają rozszerzenie .ndjson. Jest ono powszechnie stosowane w narzędziach do inżynierii danych, API Elasticsearch do operacji zbiorczych i strumieniowych odpowiedziach HTTP. Wiele edytorów obsługuje też podświetlanie składni w plikach .ndjson.
3. Typ MIME
Format nie ma oficjalnie zarejestrowanego typu MIME. Powszechnie używane nieoficjalne typy to application/jsonl i application/json-lines. W praktyce wiele systemów używa application/jsonl lub zastępuje go ogólnym application/json.
Format używa typu MIME application/x-ndjson. Jest on szerzej rozpoznawany przy obsłudze HTTP. Korzystają z niego Elasticsearch, standard strumieniowania Fetch API oraz różne frameworki webowe do przesyłania odpowiedzi strumieniowych.
4. Popularność w społecznościach i ekosystemach
Format dominuje w ekosystemie AI/ML. OpenAI, Anthropic, Google Gemini, Hugging Face i większość frameworków ML korzysta z .jsonl. Nazwa 'JSONL' jest częściej wyszukiwana i ogólnie lepiej znana wśród programistów.
Format jest preferowany w inżynierii danych i systemach backendowych. Korzystają z niego Elasticsearch, Apache Spark, PostgreSQL COPY i liczne narzędzia do agregacji logów. Pakiet ndjson w npm jest pobierany miliony razy tygodniowo.
Kiedy wybrać JSONL, a kiedy NDJSON?
- Przygotowujesz dane treningowe do fine-tuningu modeli LLM w OpenAI, Anthropic lub innych usługach
- Pracujesz ze zbiorami danych Hugging Face
- Budujesz pipeline’y ML i wstępnie przetwarzasz dane
- Twój zespół lub dokumentacja posługuje się nazwą 'JSON Lines'
- Przesyłasz pliki na platformy AI/ML, które wymagają rozszerzenia .jsonl
- Pracujesz w środowiskach do data science opartych na Pythonie
- Przesyłasz dane JSON strumieniowo przez HTTP (Server-Sent Events, fetch streaming)
- Korzystasz z API Elasticsearch do operacji zbiorczych
- Budujesz pipeline’y danych z użyciem Apache Spark lub podobnych narzędzi
- Ustawiasz nagłówki Content-Type (application/x-ndjson)
- W Twojej infrastrukturze lub zespole przyjęto konwencję NDJSON
- Korzystasz z bibliotek Node.js do obsługi strumieni
Przykłady kodu: odczyt JSONL i NDJSON
# Odczyt JSONL - dokładnie tak samo jak odczyt NDJSON
import json
with open('data.jsonl', 'r') as f:
for line in f:
record = json.loads(line.strip())
print(record['text'])
# Wyjście:
# Hello world
# How are you?
# Goodbye// Odczyt NDJSON - dokładnie tak samo jak odczyt JSONL
import { createReadStream } from 'fs';
import { createInterface } from 'readline';
const rl = createInterface({
input: createReadStream('data.ndjson')
});
for await (const line of rl) {
const record = JSON.parse(line);
console.log(record.text);
}
// Wyjście:
// Hello world
// How are you?
// GoodbyeSprawdź poprawność plików JSONL / NDJSON
Sprawdź, czy Twój plik .jsonl lub .ndjson jest poprawnie sformatowany. Nasz bezpłatny walidator weryfikuje poprawność składni JSON w każdej linii.
Wszystko o NDJSON: specyfikacja, typ MIME, odczyt i zapis w Pythonie oraz Node.js, strumieniowe API HTTP, narzędzia ekosystemu i związek NDJSON z JSONL.
Waliduj pliki JSONL linia po linii. Od razu wykrywaj błędy składni, problemy z kodowaniem i niezgodności z formatem.
Dowiedz się, czym jest JSONL (JSON Lines), czym różni się od zwykłego JSON i dlaczego jest tak chętnie wybierany do strumieniowego przetwarzania danych, zapisywania logów i przechowywania zbiorów danych do uczenia maszynowego.
Dowiedz się, jak strumieniować dane JSONL w Node.js i Pythonie. Obejmuje SSE, WebSockets i przetwarzanie logów w czasie rzeczywistym.
Szczegółowe porównanie formatów JSON i JSONL. Dowiedz się, kiedy wybrać każdy z nich, poznaj ich zalety i wady oraz sposoby konwersji między nimi.