Autor: Jerry Fan

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

CechaJSONL (JSON Lines)NDJSON
Pełna nazwaJSON LinesNewline Delimited JSON
Rozszerzenie pliku.jsonl.ndjson
Specyfikacjajsonlines.org (nieformalna)github.com/ndjson/ndjson-spec (nieformalna specyfikacja)
PochodzenieKonwencja przyjęta przez społeczność, spopularyzowana przez narzędzia do data scienceFormat zaproponowany przez Chrisa Olaha, Thorstena Balla i innych
Separator linii\n (znak nowej linii)\n (znak nowej linii)
Typ MIMEapplication/jsonl (nieoficjalny)application/x-ndjson
Obsługa strumieniowaniaTak, linia po liniiTak, linia po linii
ZastosowanieOpenAI, Hugging Face, ekosystem ML/AIElasticsearch, 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.

data.jsonl
{"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.

data.ndjson
{"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

JSONL

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.

NDJSON

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

JSONL

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ę.

NDJSON

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

JSONL

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.

NDJSON

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

JSONL

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.

NDJSON

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?

JSONLUżywaj .jsonl, gdy:
  • 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
NDJSONUżywaj .ndjson, gdy:
  • 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 pliku .jsonl (Python)
# 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 pliku .ndjson (JavaScript/Node.js)
// 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?
// Goodbye

Przeglądaj pliki JSONL i NDJSON od razu

Otwieraj w przeglądarce pliki .jsonl i .ndjson o rozmiarze do 1GB. Bez wysyłania plików na serwer i bez rejestracji — narzędzie bez problemu obsługuje oba formaty.

Najczęściej zadawane pytania

Źródła