Autor: Jerry Fan

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.

Przykład NDJSON (3 rekordy)
{"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.

CechaJSONJSONLNDJSON
Pełna nazwaJavaScript Object NotationJSON LinesNewline Delimited JSON
Rozszerzenie pliku.json.jsonl.ndjson
Typ MIMEapplication/jsonapplication/jsonl (nieoficjalny)application/x-ndjson
SpecyfikacjaRFC 8259 (standard IETF)jsonlines.org (specyfikacja społecznościowa)github.com/ndjson/ndjson-spec (specyfikacja społecznościowa)
Separator liniiNie dotyczy (pojedyncza wartość)\n (nowa linia)\n (nowa linia)
Końcowy znak nowej liniiNie dotyczyZalecanyOpcjonalny
Przetwarzanie strumienioweNie (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.

Nagłówek Content-Type w HTTP
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.

Python: odczyt i zapis NDJSON
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.

Node.js: odczyt i zapis NDJSON
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.

Wiersz poleceń: przetwarzanie NDJSON za pomocą jq
# 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.ndjson

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

Serwer przesyłający strumień NDJSON w Express.js
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);
Przeglądarka: odbieranie strumienia NDJSON za pomocą Fetch
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ędny

jq 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

CLI

ndjson-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.js

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

JSONL a NDJSON: szczegółowe porównanie

Więcej o historii obu formatów, różnicach w ich specyfikacjach i popularności w społeczności programistów dowiesz się z naszego osobnego poradnika porównującego JSONL i NDJSON.

Pracuj z plikami NDJSON online

Przeglądaj, waliduj i konwertuj pliki NDJSON i JSONL o rozmiarze do 1 GB bezpośrednio w przeglądarce. Bez przesyłania plików na serwer, ze 100% prywatnością.

Najczęściej zadawane pytania

Źródła