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が含まれていても、ほかの行は正常にパースできます。このようにエラーの影響を受けにくいため、アプリケーションログ、イベントストリーム、データの差分エクスポートなど、追記のみを行うワークフローに適しています。
{"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つのフォーマットの主な違いをまとめます。
| 比較項目 | JSON | JSONL | NDJSON |
|---|---|---|---|
| 正式名称 | JavaScript Object Notation | JSON Lines | Newline Delimited JSON |
| ファイル拡張子 | .json | .jsonl | .ndjson |
| MIMEタイプ | application/json | application/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タイプを使っています。
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を使います。このように行単位で処理すれば、大きなファイルでもメモリ使用量を一定に保てます。
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行ずつ処理するため、ファイルサイズにかかわらずメモリ使用量を抑えられます。
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フラグを指定すると全レコードを単一の配列にまとめられ、フラグを指定しなければレコードを個別に処理できます。
# 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.ndjsonHTTPストリーミング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を扱うツールとライブラリ
NDJSONに標準で対応したコマンドラインツールやライブラリは、ますます充実しています。これらを使えば、独自のコードを書かずにNDJSONデータのフィルタリング、変換、分析ができます。
jq
必須jqは、コマンドラインでJSONを処理するツールとして最も広く使われています。デフォルトでNDJSON(1行に1つのJSON値)を読み込めるほか、フィルタリング、マッピング、グループ化、整形に対応しています。コンパクトに出力するにはjq -cを、全レコードを単一の配列にまとめるにはjq -sを使います。
ndjson-cli
CLIndjson-cliは、NDJSONストリームを操作するUnixスタイルのコマンド群です。ndjson-filter、ndjson-map、ndjson-reduce、ndjson-sort、ndjson-joinが用意されています。各コマンドはstdinから読み込み、stdoutへ書き出すため、パイプでつないで組み合わせられます。
ndjson(npm)
Node.jsnpmパッケージの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ファイルも変更せずに扱えます。
無料のNDJSON/JSONLツールを試す
ブラウザ上でNDJSONとJSONLファイルを操作できます。処理はすべてローカルで行われるため、データのプライバシーを保てます。
JSONL と NDJSON(Newline Delimited JSON)の関係を解説します。両者の微妙な違いと、用語の使い分けを紹介します。
JSONL ファイルを 1 行ずつ検証します。構文エラーや文字エンコーディング、形式の問題をすぐに検出できます。
Node.jsとPythonでJSONLデータをストリーミングする方法を学びます。SSE、WebSocket、リアルタイムログ処理をカバー。
JSONL(JSON Lines)とは何か、通常の JSON とどう違うのかを解説します。ストリーミングデータ、ログファイル、機械学習のデータセットで選ばれる理由も紹介します。
JSONL ファイルを標準的な JSON 配列に変換できます。API やデータ処理パイプラインでの利用に適しています。