NDJSON完全ガイド：改行区切りJSON徹底解説

NDJSONの仕様

github.com/ndjson/ndjson-specの公式NDJSON仕様は意図的にミニマルです。単一のテキストストリームで複数のJSON値をシリアライズするためのシンプルな慣例を定義しています。コアルールは簡潔です：

仕様はフォーマットにヘッダー、メタデータ、スキーマ情報を追加することを明示的に避けています。これにより、NDJSONは可能な限りシンプルに保たれ、標準的なUnixテキスト処理ツールと互換性があります。各行には任意の有効なJSON値が許可されますが、実際にはほとんどのNDJSONファイルは一貫したキーセットを持つJSONオブジェクトを含んでいます。

• 各行には正確に1つの有効なJSON値（オブジェクト、配列、文字列、数値、ブール値、またはnull）を含める必要があります。
• 行は改行文字 '\n'（U+000A）で区切られます。キャリッジリターン '\r'（U+000D）は '\n' の前に表示される場合がありますが、必須ではありません。
• 最後のJSON値の後の末尾の改行は許可されますが、必須ではありません。
• 各JSON値には、値自体の中にエスケープされていない改行文字を含めてはなりません。

ルールがミニマルであるため、NDJSONはJSONシリアライザーを持つ任意のプログラミング言語から簡単に生成できます。各レコードをシリアライズし、改行を追加して出力に書き込むだけです。閉じ括弧も、末尾のカンマも、囲む配列構造も気にする必要がありません。

NDJSON MIMEタイプ：application/x-ndjson

NDJSONの登録済みMIMEタイプはapplication/x-ndjsonです。このコンテンツタイプは、レスポンスボディが改行区切りのJSONデータを含むことを示すためにHTTPヘッダーで使用されます。GitHub API、Docker Registry API、Elasticsearch Bulk APIを含む多くのストリーミングAPIが、NDJSONレスポンスを配信するためにこのMIMEタイプを使用しています。

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');

一部のAPIは代替としてapplication/json-seq（RFC 7464）やtext/plainも受け付けます。ただし、application/x-ndjsonは改行区切りJSONストリームで最も広く採用されているMIMEタイプです。JSONレコードをストリーミングする新しいAPIを構築する場合は、最大限の互換性のためにapplication/x-ndjsonを使用してください。

HTTPストリーミングAPIでのNDJSON

NDJSONはリアルタイムデータを配信するHTTPストリーミングAPIの事実上の標準です。サーバーがNDJSONレスポンスを送信すると、クライアントはレスポンス全体の完了を待つことなく、最初のレコードが到着した時点で処理を開始できます。これは大きなJSON配列を返すよりも高速でメモリ効率が良いです。

NDJSONストリーミングを使用する人気のあるサービスには、Docker Registry（イメージレイヤーイベント）、Elasticsearch（バルク操作）、Apache CouchDB（変更フィード）、および多くの最新のイベント駆動型APIがあります。このパターンは、Server-Sent Eventsの代替、リアルタイムログテーリング、Webアプリケーションでのプログレッシブデータロードに適しています。

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とJSONL：相互運用性

NDJSONとJSONL（JSON Lines）は機能的に同一のフォーマットです。どちらも改行で区切られた1行に1つのJSON値を格納します。有効なNDJSONファイルは有効なJSONLでもあり、その逆もまた然りです。.ndjsonファイルを.jsonlに（またはその逆に）ファイル名を変更しても、コンテンツの1バイトも変更することなく、一方のフォーマットを読み取るすべてのツールが他方も読み取ります。

唯一の違いは外見的なものです：NDJSONはgithub.com/ndjson/ndjson-specに由来し、.ndjson拡張子とapplication/x-ndjson MIMEタイプを使用し、JSONLはjsonlines.orgに由来し、.jsonl拡張子を使用します。実際には、ほとんどの開発者は2つの名前を同義語として扱います。プロジェクトですでにJSONLを使用している場合、NDJSONに移行する必要はなく、ライブラリがNDJSONをサポートしていると言っている場合、変更なしで.jsonlファイルでも動作します。