- Strona główna
- Przewodnik
- NDJSON — kompletny przewodnik po Newline Delimited JSON
NDJSON — kompletny przewodnik po Newline Delimited JSON
Kompletny przewodnik po formacie Newline Delimited JSON (NDJSON). Poznaj jego specyfikację i typ MIME, naucz się odczytywać i zapisywać NDJSON w Pythonie, Node.js oraz z wiersza poleceń, a także używać go w strumieniowych API HTTP. Dowiedz się też, jak NDJSON ma się do JSONL.
Czym jest NDJSON?
NDJSON to skrót od Newline Delimited JSON. Jest to tekstowy format danych, w którym każda linia zawiera dokładnie jedną poprawną wartość JSON, a poszczególne linie rozdziela znak nowej linii (\n). Format powstał z myślą o strumieniowym przesyłaniu i przetwarzaniu dużych zbiorów danych bez wczytywania całego pliku do pamięci. Standardowy plik JSON ujmuje całość danych w jednej tablicy lub jednym obiekcie, natomiast NDJSON pozwala odczytywać, zapisywać i przetwarzać rekordy pojedynczo.
Specyfikacja NDJSON jest dostępna pod adresem github.com/ndjson/ndjson-spec. Powstała, by sformalizować sposób zapisu, który był już powszechnie stosowany przy przesyłaniu logów, w potokach przetwarzania danych i strumieniowych API HTTP. Każda linia stanowi niezależną całość: jeśli jedna zawiera niepoprawny JSON, pozostałe nadal można poprawnie sparsować. Dzięki temu NDJSON jest odporny na błędy i dobrze sprawdza się tam, gdzie dane są wyłącznie dopisywane — na przykład w logach aplikacji, strumieniach zdarzeń i przyrostowym eksporcie danych.
{"id":1,"event":"page_view","url":"/home"}
{"id":2,"event":"click","url":"/pricing"}
{"id":3,"event":"signup","url":"/register"}Specyfikacja NDJSON
Oficjalna specyfikacja NDJSON, dostępna pod adresem github.com/ndjson/ndjson-spec, jest celowo zwięzła. Określa prostą konwencję serializacji wielu wartości JSON w jednym strumieniu tekstowym. Jej podstawowe zasady to:
Specyfikacja celowo nie wprowadza do formatu nagłówków, metadanych ani informacji o schemacie. Dzięki temu NDJSON pozostaje możliwie prosty i zgodny ze standardowymi uniksowymi narzędziami do przetwarzania tekstu. Każda linia może zawierać dowolną poprawną wartość JSON, choć w praktyce większość plików NDJSON zawiera obiekty JSON o spójnym zestawie kluczy.
- Każda linia MUSI zawierać dokładnie jedną poprawną wartość JSON (obiekt, tablicę, ciąg znaków, liczbę, wartość logiczną lub null).
- Linie rozdziela znak nowej linii '\n' (U+000A). Przed '\n' może występować znak powrotu karetki '\r' (U+000D), ale nie jest on wymagany.
- Znak nowej linii po ostatniej wartości JSON jest dozwolony, ale nie jest wymagany.
- Wartość JSON nie może zawierać znaków nowej linii niezapisanych jako sekwencje ucieczki.
Tak niewielki zestaw reguł sprawia, że NDJSON łatwo wygenerować w dowolnym języku programowania wyposażonym w serializator JSON. Wystarczy zserializować każdy rekord, dopisać znak nowej linii i zapisać wynik na wyjściu. Nie trzeba pilnować nawiasów zamykających, końcowych przecinków ani tablicy obejmującej wszystkie rekordy.
NDJSON vs JSON vs JSONL
NDJSON, JSON i JSONL różnią się strukturą. Standardowy JSON koduje pojedynczą wartość (zwykle tablicę lub obiekt). JSONL i NDJSON zapisują po jednej wartości JSON w każdej linii i są funkcjonalnie identyczne. Poniższa tabela przedstawia najważniejsze różnice między tymi trzema formatami.
| Cecha | JSON | JSONL | NDJSON |
|---|---|---|---|
| Pełna nazwa | JavaScript Object Notation | JSON Lines | Newline Delimited JSON |
| Rozszerzenie pliku | .json | .jsonl | .ndjson |
| Typ MIME | application/json | application/jsonl (nieoficjalny) | application/x-ndjson |
| Specyfikacja | RFC 8259 (standard IETF) | jsonlines.org (specyfikacja społecznościowa) | github.com/ndjson/ndjson-spec (specyfikacja społecznościowa) |
| Separator linii | Nie dotyczy (pojedyncza wartość) | \n (nowa linia) | \n (nowa linia) |
| Końcowy znak nowej linii | Nie dotyczy | Zalecany | Opcjonalny |
| Przetwarzanie strumieniowe | Nie (trzeba sparsować cały dokument) | Tak (linia po linii) | Tak (linia po linii) |
Typ MIME NDJSON: application/x-ndjson
Zarejestrowany typ MIME dla NDJSON to application/x-ndjson. W nagłówkach HTTP oznacza on, że treść odpowiedzi zawiera dane JSON rozdzielone znakami nowej linii. Wiele strumieniowych API, w tym GitHub API, Docker Registry API i Elasticsearch bulk API, używa tego typu MIME w odpowiedziach NDJSON.
Content-Type: application/x-ndjson
# Example: curl a streaming API
curl -H "Accept: application/x-ndjson" https://api.example.com/events/stream
# Example: Express.js response
res.setHeader('Content-Type', 'application/x-ndjson');
res.write(JSON.stringify(record) + '\n');Niektóre API akceptują również application/json-seq (RFC 7464) lub text/plain. Najpowszechniej stosowanym typem MIME dla strumieni JSON rozdzielanych znakami nowej linii jest jednak application/x-ndjson. Jeśli tworzysz nowe API przesyłające strumień rekordów JSON, użyj application/x-ndjson, aby zapewnić jak najszerszą zgodność.
Odczyt i zapis NDJSON
Obsługa NDJSON jest prosta w każdym języku obsługującym JSON. Poniżej znajdziesz praktyczne przykłady w Pythonie, Node.js i wierszu poleceń.
Do obsługi NDJSON wystarczy wbudowany w Pythona moduł json. Odczytuj kolejne linie pliku i parsuj je za pomocą json.loads, a do zapisu użyj json.dumps. Przy dużych plikach przetwarzanie linia po linii pozwala utrzymać stałe zużycie pamięci.
import json
# Read NDJSON
records = []
with open('data.ndjson', 'r') as f:
for line in f:
line = line.strip()
if line:
records.append(json.loads(line))
print(f'Loaded {len(records)} records')
# Write NDJSON
output = [
{'id': 1, 'event': 'page_view', 'url': '/home'},
{'id': 2, 'event': 'click', 'url': '/pricing'},
{'id': 3, 'event': 'signup', 'url': '/register'},
]
with open('output.ndjson', 'w') as f:
for record in output:
f.write(json.dumps(record) + '\n')W Node.js użyj modułu readline w połączeniu z fs.createReadStream, aby sprawnie parsować pliki NDJSON. Strumień przetwarza po jednej linii, dzięki czemu zużycie pamięci pozostaje niewielkie niezależnie od rozmiaru pliku.
import { createReadStream, writeFileSync } from 'node:fs';
import { createInterface } from 'node:readline';
// Read NDJSON
async function readNdjson(filePath) {
const records = [];
const rl = createInterface({
input: createReadStream(filePath, 'utf-8'),
crlfDelay: Infinity,
});
for await (const line of rl) {
const trimmed = line.trim();
if (trimmed) records.push(JSON.parse(trimmed));
}
return records;
}
// Write NDJSON
const data = [
{ id: 1, event: 'page_view' },
{ id: 2, event: 'click' },
];
const ndjson = data.map(r => JSON.stringify(r)).join('\n') + '\n';
writeFileSync('output.ndjson', ndjson, 'utf-8');Narzędzie jq ma wbudowaną obsługę danych wejściowych w formacie NDJSON. Użyj opcji --slurp, aby zebrać wszystkie rekordy w tablicy, albo przetwarzaj je pojedynczo bez dodatkowych opcji.
# Print each record (jq reads NDJSON by default)
jq '.' data.ndjson
# Filter records where event is "click"
jq 'select(.event == "click")' data.ndjson
# Extract specific fields
jq '{id, url}' data.ndjson
# Count total records
jq -s 'length' data.ndjson
# Convert NDJSON to a JSON array
jq -s '.' data.ndjson > data.json
# Convert a JSON array back to NDJSON
jq -c '.[]' data.json > data.ndjsonNDJSON w strumieniowych API HTTP
NDJSON jest de facto standardem w strumieniowych API HTTP dostarczających dane w czasie rzeczywistym. Gdy serwer wysyła odpowiedź NDJSON, klient może rozpocząć przetwarzanie pierwszego rekordu od razu po jego otrzymaniu, bez czekania na całą odpowiedź. To szybsze i oszczędniejsze pod względem pamięci niż zwracanie dużej tablicy JSON.
Ze strumieniowania NDJSON korzystają między innymi Docker Registry (zdarzenia dotyczące warstw obrazów), Elasticsearch (operacje masowe), Apache CouchDB (strumień zmian) i wiele nowoczesnych API opartych na zdarzeniach. Takie podejście sprawdza się w rozwiązaniach alternatywnych wobec Server-Sent Events, przy śledzeniu logów w czasie rzeczywistym i stopniowym wczytywaniu danych w aplikacjach webowych.
import express from 'express';
const app = express();
app.get('/api/events/stream', (req, res) => {
res.setHeader('Content-Type', 'application/x-ndjson');
res.setHeader('Transfer-Encoding', 'chunked');
// Simulate streaming events
let id = 0;
const interval = setInterval(() => {
id++;
const event = {
id,
type: 'heartbeat',
timestamp: new Date().toISOString(),
};
res.write(JSON.stringify(event) + '\n');
if (id >= 100) {
clearInterval(interval);
res.end();
}
}, 100);
req.on('close', () => clearInterval(interval));
});
app.listen(3000);async function* readNdjsonStream(url) {
const response = await fetch(url, {
headers: { 'Accept': 'application/x-ndjson' },
});
const reader = response.body
.pipeThrough(new TextDecoderStream())
.getReader();
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += value;
const lines = buffer.split('\n');
buffer = lines.pop();
for (const line of lines) {
if (line.trim()) yield JSON.parse(line);
}
}
if (buffer.trim()) yield JSON.parse(buffer);
}
// Usage
for await (const event of readNdjsonStream('/api/events/stream')) {
console.log('Received:', event);
}Narzędzia do pracy z NDJSON
NDJSON ma wbudowaną obsługę w coraz większej liczbie narzędzi wiersza poleceń i bibliotek. Pozwalają one filtrować, przekształcać i analizować dane NDJSON bez pisania własnego kodu.
jq
Niezbędnyjq to najpopularniejsze narzędzie wiersza poleceń do przetwarzania JSON. Domyślnie odczytuje NDJSON (jedna wartość JSON w każdej linii) i obsługuje filtrowanie, mapowanie, grupowanie oraz zmianę formatowania. Użyj jq -c, aby uzyskać zwarty zapis na wyjściu, lub jq -s, aby zebrać wszystkie rekordy w tablicy.
ndjson-cli
CLIndjson-cli to zestaw uniksowych poleceń do przetwarzania strumieni NDJSON: ndjson-filter, ndjson-map, ndjson-reduce, ndjson-sort i ndjson-join. Każde polecenie odczytuje dane ze stdin i zapisuje wynik na stdout, dzięki czemu można je łączyć w potoki.
ndjson (npm)
Node.jsPakiet ndjson z npm udostępnia strumieniowe parsery i serializatory NDJSON dla Node.js. Oferuje strumienie transformujące ndjson.parse() i ndjson.stringify(), które można bezpośrednio włączać w potoki strumieni Node.js, aby przetwarzać dane z dużą przepustowością.
Zgodność NDJSON i JSONL
NDJSON i JSONL (JSON Lines) to funkcjonalnie identyczne formaty. W obu każda linia zawiera jedną wartość JSON, a linie rozdziela znak nowej linii. Poprawny plik NDJSON jest również poprawnym plikiem JSONL i odwrotnie. Możesz zmienić rozszerzenie pliku z .ndjson na .jsonl (lub odwrotnie) bez zmiany choćby jednego bajta jego zawartości, a każde narzędzie obsługujące jeden z tych formatów odczyta też drugi.
Różnice są wyłącznie kosmetyczne: NDJSON wywodzi się ze specyfikacji github.com/ndjson/ndjson-spec i używa rozszerzenia .ndjson oraz typu MIME application/x-ndjson, a JSONL wywodzi się z jsonlines.org i używa rozszerzenia .jsonl. W praktyce większość programistów traktuje te nazwy jako synonimy. Jeśli w Twoim projekcie używasz już JSONL, nie musisz przechodzić na NDJSON. Z kolei biblioteka deklarująca obsługę NDJSON będzie działać z Twoimi plikami .jsonl bez żadnych zmian.
Wypróbuj nasze bezpłatne narzędzia NDJSON/JSONL
Pracuj z plikami NDJSON i JSONL bezpośrednio w przeglądarce. Całe przetwarzanie odbywa się lokalnie, więc Twoje dane pozostają prywatne.
Poznaj związek między JSONL a NDJSON (Newline Delimited JSON). Dowiedz się, jakie subtelne różnice je dzielą i kiedy używać poszczególnych nazw.
Waliduj pliki JSONL linia po linii. Od razu wykrywaj błędy składni, problemy z kodowaniem i niezgodności z formatem.
Dowiedz się, jak strumieniować dane JSONL w Node.js i Pythonie. Obejmuje SSE, WebSockets i przetwarzanie logów w czasie rzeczywistym.
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.
Konwertuj pliki JSONL na standardową tablicę JSON. To idealne rozwiązanie do pracy z API i pipeline’ami przetwarzania danych.