著者: Jerry Fan

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

Newline Delimited JSON(NDJSON)を詳しく解説するガイドです。仕様やMIMEタイプ、Python・Node.js・コマンドラインでの読み書き、HTTPストリーミングAPIでの使い方から、JSONLとの関係まで紹介します。

NDJSONとは?

NDJSONはNewline Delimited JSONの略で、各行に1つずつ有効なJSON値を記述し、改行文字(\n)で区切るテキスト形式のデータフォーマットです。ファイル全体をメモリに読み込まずに、大規模なデータセットをストリーミングで処理できるように設計されています。標準的なJSONファイルではデータ全体を単一の配列やオブジェクトで囲みますが、NDJSONではレコードを1つずつ読み書きし、処理できます。

NDJSONの仕様はgithub.com/ndjson/ndjson-specで公開されています。ログ転送やデータパイプライン、HTTPストリーミングAPIですでに広く使われていた記述方法を、仕様として定めたものです。各行は独立しているため、1行に不正なJSONが含まれていても、ほかの行は正常にパースできます。このようにエラーの影響を受けにくいため、アプリケーションログ、イベントストリーム、データの差分エクスポートなど、追記のみを行うワークフローに適しています。

NDJSONの例(3レコード)
{"id":1,"event":"page_view","url":"/home"}
{"id":2,"event":"click","url":"/pricing"}
{"id":3,"event":"signup","url":"/register"}

NDJSONの仕様

github.com/ndjson/ndjson-specで公開されているNDJSONの公式仕様は、意図的に最小限のルールに絞られています。単一のテキストストリームに複数のJSON値をシリアライズするための、シンプルな規約です。基本的なルールは次のとおりです。

仕様では、ヘッダーやメタデータ、スキーマ情報をフォーマットに含めない方針を明確にしています。これにより、NDJSONをできる限りシンプルに保ち、標準的なUnixのテキスト処理ツールで扱えるようにしています。各行には有効なJSON値であれば何でも記述できますが、実際のNDJSONファイルでは、同じキー構成のJSONオブジェクトを並べることがほとんどです。

  • 各行には、有効なJSON値(オブジェクト、配列、文字列、数値、ブール値、nullのいずれか)を必ず1つだけ記述します。
  • 行は改行文字 '\n'(U+000A)で区切ります。'\n' の直前にキャリッジリターン '\r'(U+000D)を置くこともできますが、必須ではありません。
  • 最後のJSON値の後に改行を入れることもできますが、必須ではありません。
  • JSON値の内部に、エスケープされていない改行文字を含めてはいけません。

ルールが少ないため、JSONシリアライザーを備えたプログラミング言語であれば、どの言語でも簡単にNDJSONを生成できます。各レコードをシリアライズし、改行を付けて出力するだけです。データ全体を囲む配列やその閉じ括弧、末尾のカンマを気にする必要はありません。

NDJSON vs JSON vs JSONL

NDJSON、JSON、JSONLの構造を比較してみましょう。標準のJSONは、単一の値(通常は配列またはオブジェクト)をエンコードします。一方、JSONLとNDJSONは、どちらも1行に1つのJSON値を格納し、機能的には同じ形式です。次の表に、3つのフォーマットの主な違いをまとめます。

比較項目JSONJSONLNDJSON
正式名称JavaScript Object NotationJSON LinesNewline Delimited JSON
ファイル拡張子.json.jsonl.ndjson
MIMEタイプapplication/jsonapplication/jsonl(非公式)application/x-ndjson
仕様RFC 8259(IETF標準)jsonlines.org(コミュニティ)github.com/ndjson/ndjson-spec(コミュニティ)
行区切り文字該当なし(単一の値)\n(改行)\n(改行)
末尾の改行N/A推奨任意
ストリーミング対応非対応(ドキュメント全体のパースが必要)対応(行単位)対応(行単位)

NDJSONのMIMEタイプ:application/x-ndjson

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

HTTP Content-Typeヘッダー
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も受け付けます。ただし、改行区切りのJSONストリームで最も広く採用されているMIMEタイプはapplication/x-ndjsonです。JSONレコードをストリーミング配信するAPIを新しく作る場合は、互換性を最大限に確保できるよう、application/x-ndjsonを使用してください。

NDJSONの読み書き

JSONに対応した言語であれば、NDJSONは簡単に扱えます。ここでは、Python、Node.js、コマンドラインでの実用的な例を紹介します。

Pythonでは、標準ライブラリのjsonモジュールでNDJSONを扱えます。ファイルを行ごとに読み込んでjson.loadsでパースし、書き込みにはjson.dumpsを使います。このように行単位で処理すれば、大きなファイルでもメモリ使用量を一定に保てます。

Pythonで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')

Node.jsでは、readlineモジュールとfs.createReadStreamを組み合わせると、NDJSONファイルを効率よくパースできます。ストリームで1行ずつ処理するため、ファイルサイズにかかわらずメモリ使用量を抑えられます。

Node.jsで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');

コマンドラインツールのjqは、NDJSON形式の入力に標準で対応しています。--slurpフラグを指定すると全レコードを単一の配列にまとめられ、フラグを指定しなければレコードを個別に処理できます。

コマンドラインでjqを使ってNDJSONを処理する
# 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

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

NDJSONは、リアルタイムデータを配信するHTTPストリーミングAPIで事実上の標準となっています。サーバーがNDJSONレスポンスを返すと、クライアントはレスポンス全体の受信を待たずに、最初のレコードが届いた時点で処理を開始できます。大きなJSON配列を返す方法に比べ、高速でメモリ効率にも優れています。

NDJSONストリーミングを採用している代表的なサービスには、Docker Registry(イメージレイヤーのイベント)、Elasticsearch(バルク操作)、Apache CouchDB(変更フィード)などがあり、多くのモダンなイベント駆動型APIでも使われています。Server-Sent Eventsの代替手段としても、ログをリアルタイムで追跡する場合や、Webアプリケーションでデータを段階的に読み込む場合にも適しています。

Express.jsでNDJSONストリーミングサーバーを作る
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);
ブラウザでFetchを使ってNDJSONストリームを読み込む
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を扱うツールとライブラリ

NDJSONに標準で対応したコマンドラインツールやライブラリは、ますます充実しています。これらを使えば、独自のコードを書かずにNDJSONデータのフィルタリング、変換、分析ができます。

jq

必須

jqは、コマンドラインでJSONを処理するツールとして最も広く使われています。デフォルトでNDJSON(1行に1つのJSON値)を読み込めるほか、フィルタリング、マッピング、グループ化、整形に対応しています。コンパクトに出力するにはjq -cを、全レコードを単一の配列にまとめるにはjq -sを使います。

ndjson-cli

CLI

ndjson-cliは、NDJSONストリームを操作するUnixスタイルのコマンド群です。ndjson-filter、ndjson-map、ndjson-reduce、ndjson-sort、ndjson-joinが用意されています。各コマンドはstdinから読み込み、stdoutへ書き出すため、パイプでつないで組み合わせられます。

ndjson(npm)

Node.js

npmパッケージのndjsonは、Node.js向けのストリーミング対応NDJSONパーサーとシリアライザーを提供します。ndjson.parse()とndjson.stringify()をTransformストリームとして利用でき、Node.jsのストリームパイプラインにそのまま組み込んで、高いスループットでデータを処理できます。

NDJSONとJSONLの相互運用性

NDJSONとJSONL(JSON Lines)は、機能的には同じフォーマットです。どちらも1行に1つのJSON値を格納し、改行文字で区切ります。有効なNDJSONファイルはJSONLとしても有効で、逆も同様です。.ndjsonファイルの拡張子を.jsonlに変更しても、その逆でも、内容を1バイトも変える必要はありません。一方の形式を読み込めるツールなら、もう一方も読み込めます。

違うのは、由来や拡張子などの表面的な部分だけです。NDJSONはgithub.com/ndjson/ndjson-specに由来し、拡張子に.ndjson、MIMEタイプにapplication/x-ndjsonを使います。一方、JSONLはjsonlines.orgに由来し、拡張子に.jsonlを使います。実際には、ほとんどの開発者が2つの名前を同じ意味で使っています。すでにJSONLを使っているプロジェクトで、NDJSONへ移行する必要はありません。NDJSON対応をうたうライブラリなら、.jsonlファイルも変更せずに扱えます。

JSONLとNDJSONの詳しい比較

JSONLとNDJSONの歴史や仕様の違い、コミュニティでの採用状況をさらに詳しく知りたい方は、比較ガイドをご覧ください。

NDJSONファイルをオンラインで操作

最大1GBのNDJSON・JSONLファイルをブラウザ上で表示、検証、変換できます。アップロードは不要で、データのプライバシーは100%保たれます。

よくある質問

参考資料