Kompletny przewodnik NDJSON: Wyjaśnienie Newline Delimited JSON

Specyfikacja NDJSON

Oficjalna specyfikacja NDJSON na github.com/ndjson/ndjson-spec jest celowo minimalistyczna. Definiuje prostą konwencję serializacji wielu wartości JSON w jednym strumieniu tekstowym. Podstawowe zasady są proste:

Specyfikacja celowo unika dodawania nagłówków, metadanych lub informacji o schemacie do formatu. Dzięki temu NDJSON jest tak prosty, jak to możliwe, i kompatybilny ze standardowymi narzędziami uniksowymi do przetwarzania tekstu. Każda prawidłowa wartość JSON jest dozwolona w każdej linii, chociaż w praktyce większość plików NDJSON zawiera obiekty JSON ze spójnym zestawem kluczy.

• Każda linia MUSI zawierać dokładnie jedną prawidłową wartość JSON (obiekt, tablicę, ciąg znaków, liczbę, wartość logiczną lub null).
• Linie są oddzielane znakiem nowej linii '\n' (U+000A). Znak powrotu karetki '\r' (U+000D) może pojawić się przed '\n', ale nie jest wymagany.
• Końcowy znak nowej linii po ostatniej wartości JSON jest dozwolony, ale nie wymagany.
• Każda wartość JSON nie może zawierać niezamaskowanych znaków nowej linii wewnątrz samej wartości.

Ponieważ zasady są minimalne, NDJSON jest łatwy do wygenerowania z dowolnego języka programowania, który posiada serializator JSON. Wystarczy serializować każdy rekord, dopisać znak nowej linii i zapisać do wyjścia. Żadnych zamykających nawiasów, żadnych końcowych przecinków, żadnej otaczającej struktury tablicy do zarządzania.

Typ MIME NDJSON: application/x-ndjson

Zarejestrowany typ MIME dla NDJSON to application/x-ndjson. Ten typ zawartości jest używany w nagłówkach HTTP, aby wskazać, że treść odpowiedzi zawiera dane JSON rozdzielane znakami nowej linii. Wiele strumieniowych API, w tym GitHub API, Docker Registry API i Elasticsearch bulk API, używa tego typu MIME do dostarczania odpowiedzi 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 jako alternatywy. Jednak application/x-ndjson jest najszerzej przyjętym typem MIME dla strumieni JSON rozdzielanych znakami nowej linii. Budując nowe API strumieniujące rekordy JSON, użyj application/x-ndjson dla maksymalnej kompatybilności.

NDJSON w strumieniowych API HTTP

NDJSON jest de facto standardem dla strumieniowych API HTTP dostarczających dane w czasie rzeczywistym. Gdy serwer wysyła odpowiedź NDJSON, klient może rozpocząć przetwarzanie pierwszego rekordu, gdy tylko dotrze, bez czekania na zakończenie całej odpowiedzi. Jest to szybsze i bardziej wydajne pamięciowo niż zwracanie dużej tablicy JSON.

Popularne usługi używające strumieniowania NDJSON to Docker Registry (zdarzenia warstw obrazów), Elasticsearch (operacje masowe), Apache CouchDB (feed zmian) oraz wiele nowoczesnych API sterowanych zdarzeniami. Ten wzorzec dobrze działa z alternatywami Server-Sent Events, śledzeniem logów w czasie rzeczywistym i progresywnym ładowaniem 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);
}

NDJSON i JSONL: Interoperacyjność

NDJSON i JSONL (JSON Lines) to funkcjonalnie identyczne formaty. Oba przechowują jedną wartość JSON na linię, oddzieloną znakami nowej linii. Plik, który jest prawidłowym NDJSON, jest również prawidłowym JSONL i odwrotnie. Możesz zmienić nazwę pliku .ndjson na .jsonl (lub odwrotnie) bez zmiany ani jednego bajta zawartości, a każde narzędzie czytające jeden format odczyta również drugi.

Jedyne różnice są kosmetyczne: NDJSON pochodzi z github.com/ndjson/ndjson-spec i używa rozszerzenia .ndjson z typem MIME application/x-ndjson, podczas gdy JSONL pochodzi z jsonlines.org i używa rozszerzenia .jsonl. W praktyce większość programistów traktuje te dwie nazwy jako synonimy. Jeśli Twój projekt już używa JSONL, nie ma potrzeby migracji do NDJSON, a jeśli biblioteka mówi, że obsługuje NDJSON, będzie działać z Twoimi plikami .jsonl bez żadnych zmian.