著者: Jerry Fan

JSONL チュートリアル:ファイルの作成・読み込み・変換

JSONL(JSON Lines)ファイルを扱うために必要な知識を、順を追って解説します。Python、JavaScript、CLI ツールを使ったコード例も紹介します。

JSONL とは?

JSONL(JSON Lines)は、各行に独立した有効な JSON 値を記述する、軽量なテキスト形式です。通常の JSON ではすべてのデータを 単一の配列やオブジェクトにまとめますが、JSONL では 1 行に 1 レコードを格納し、改行文字(\n)で区切ります。

行ごとに独立しているため、大規模なデータセットのストリーミング処理や、ファイル全体を書き直さずにレコードを追記する処理、データの並列処理に適しています。OpenAI のファインチューニング用データセットや、ELK スタックなどのログ管理システム、BigQuery や Apache Spark などのビッグデータツールで広く使われています。

example.jsonl
{"id":1,"name":"Alice","role":"engineer"}
{"id":2,"name":"Bob","role":"designer"}
{"id":3,"name":"Charlie","role":"manager"}

JSONL ファイルの作成方法

JSONL ファイルの作成は簡単です。各レコードを 改行を含まない JSON 文字列にシリアライズし、末尾に改行を付けて書き込みます。ここでは、よく使われる言語での実装例を紹介します。

Python
import json


records = [
    {"id": 1, "name": "Alice", "role": "engineer"},
    {"id": 2, "name": "Bob", "role": "designer"},
    {"id": 3, "name": "Charlie", "role": "manager"},
]


with open("output.jsonl", "w", encoding="utf-8") as f:
    for record in records:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")


print("Created output.jsonl with", len(records), "records")
JavaScript / Node.js
import { writeFileSync } from 'fs';


const records = [
  { id: 1, name: 'Alice', role: 'engineer' },
  { id: 2, name: 'Bob', role: 'designer' },
  { id: 3, name: 'Charlie', role: 'manager' },
];


const jsonl = records
  .map(record => JSON.stringify(record))
  .join('\n');


writeFileSync('output.jsonl', jsonl + '\n', 'utf-8');
console.log(`Created output.jsonl with ${records.length} records`);

テキストエディタで手動作成

JSONL ファイルは、どのテキストエディタでも作成できます。1 行に 1 つずつ有効な JSON オブジェクトを記述し、行と行の間にカンマを入れずに、拡張子を .jsonl にして保存します。各行が、それだけで完結した有効な JSON になっていることを確認してください。

JSONL ファイルの読み込み方法

各行が独立した JSON 値なので、JSONL ファイルは 行ごとに順に処理するだけで読み込めます。代表的な方法を紹介します。

Python
import json


with open("data.jsonl", "r", encoding="utf-8") as f:
    for line_number, line in enumerate(f, 1):
        line = line.strip()
        if not line:
            continue  # skip empty lines
        record = json.loads(line)
        print(f"Line {line_number}: {record['name']} - {record['role']}")
JavaScript / Node.js
import { createReadStream } from 'fs';
import { createInterface } from 'readline';


const rl = createInterface({
  input: createReadStream('data.jsonl', 'utf-8'),
});


let lineNumber = 0;
for await (const line of rl) {
  if (!line.trim()) continue; // skip empty lines
  lineNumber++;
  const record = JSON.parse(line);
  console.log(`Line ${lineNumber}: ${record.name} - ${record.role}`);
}
コマンドライン(grep / jq)
# 最初の 10 行を表示
head -n 10 data.jsonl


# 総レコード数をカウント
wc -l data.jsonl


# jq で各行を整形出力
cat data.jsonl | jq .


# role が "engineer" のレコードをフィルター
cat data.jsonl | jq 'select(.role == "engineer")'


# name フィールドのみを抽出
cat data.jsonl | jq -r '.name'


# キーワードを含む行を検索
grep '"Alice"' data.jsonl

JSON を JSONL に変換する方法

通常の JSON 配列を JSONL に変換するには、配列の各要素を 行ごとに書き出します。JSONL を扱う際によく行う操作の 1 つです。

Python
import json


# JSON 配列を読み込む
with open("data.json", "r", encoding="utf-8") as f:
    data = json.load(f)  # expects a JSON array


# JSONL として書き出す
with open("data.jsonl", "w", encoding="utf-8") as f:
    for record in data:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")


print(f"Converted {len(data)} records from JSON to JSONL")
JavaScript / Node.js
import { readFileSync, writeFileSync } from 'fs';


// JSON 配列を読み込む
const data = JSON.parse(readFileSync('data.json', 'utf-8'));


// JSONL として書き出す
const jsonl = data
  .map(record => JSON.stringify(record))
  .join('\n');


writeFileSync('data.jsonl', jsonl + '\n', 'utf-8');
console.log(`Converted ${data.length} records from JSON to JSONL`);

オンラインツールで変換する

コードを書かずに変換したい場合は、無料のオンライン JSON → JSONL 変換ツールをご利用ください。内容を貼り付けるか、ファイルをアップロードするだけですぐに変換できます。

CSV を JSONL に変換する方法

CSV を JSONL に変換するには、CSV のヘッダーをフィールド名として使い、各行を JSON オブジェクトに変換します。表形式のデータを、ストリーミング処理や機械学習に適した形式へ移行するときに便利です。

Python
import csv
import json


with open("data.csv", "r", encoding="utf-8") as csv_file:
    reader = csv.DictReader(csv_file)
    with open("data.jsonl", "w", encoding="utf-8") as jsonl_file:
        for row in reader:
            jsonl_file.write(json.dumps(row, ensure_ascii=False) + "\n")


print("Converted CSV to JSONL successfully")
JavaScript / Node.js
import { readFileSync, writeFileSync } from 'fs';


const csv = readFileSync('data.csv', 'utf-8');
const lines = csv.trim().split('\n');
const headers = lines[0].split(',');


const jsonl = lines.slice(1).map(line => {
  const values = line.split(',');
  const obj = {};
  headers.forEach((h, i) => obj[h.trim()] = values[i]?.trim());
  return JSON.stringify(obj);
}).join('\n');


writeFileSync('data.jsonl', jsonl + '\n', 'utf-8');
console.log('Converted CSV to JSONL successfully');

CSV をオンラインで変換する

無料のオンラインツールで、CSV ファイルをすぐに JSONL 形式に変換できます。コードを書く必要はありません。

JSONL のベストプラクティス

1

JSONL ファイルの文字コードは、すべて UTF-8 にしてください。プラットフォーム間の互換性を確保でき、さまざまな言語の文字を扱えます。

2

1 行には必ず 1 つの JSON オブジェクトだけを記述してください。オブジェクトを複数行に分けたり、同じ行に複数のオブジェクトを並べたりしないでください。

3

行と行の間にカンマを入れないでください。JSON 配列とは異なり、JSONL では改行文字だけを区切り文字として使います。

4

各行を個別に検証してください。すべての行が、それだけで完結した有効な JSON 値である必要があります。JSONL バリデーターを使って、構文エラーを早めに見つけましょう。

5

大きなファイルはストリーミングで読み込んでください。ファイル全体をメモリに読み込む代わりに、Node.js の readline や Python のファイルに対する反復処理を使い、行ごとに処理します。

6

レコードの構造を揃えてください。JSONL では行ごとに異なるスキーマを使えますが、構造を統一するとデータ処理が格段に楽になります。

7

行末に余分な空白を入れないでください。パース時の問題につながる可能性があるため、余分なスペースやタブが入っていないことを確認してください。

8

ファイルの末尾には改行を入れてください。最後のレコードの後に改行を入れると、wc や cat などのツールでファイルを正しく扱いやすくなります。

JSONL でよくあるエラー

全体を配列で囲んでいる
誤り
[
  {"name":"Alice"},
  {"name":"Bob"}
]
正しい
{"name":"Alice"}
{"name":"Bob"}

JSONL は JSON 配列ではありません。全体を角括弧で囲んだり、行と行の間にカンマを入れたりしないでください。各行はそれぞれ独立しています。

行の間にカンマがある
誤り
{"name":"Alice"},
{"name":"Bob"},
正しい
{"name":"Alice"}
{"name":"Bob"}

JSONL では、各行の末尾や行と行の間にカンマを入れることはできません。区切り文字として使うのは改行文字だけです。

JSON オブジェクトが複数行に分かれている
誤り
{
  "name": "Alice",
  "age": 30
}
正しい
{"name":"Alice","age":30}

各 JSON オブジェクトは、必ず 1 行に収めてください。インデントや改行を使って整形した JSON は、有効な JSONL にはなりません。

特殊文字がエスケープされていない
誤り
{"text":"She said "hello""}
正しい
{"text":"She said \"hello\""}

JSON 文字列内の引用符や特殊文字は、バックスラッシュで適切にエスケープする必要があります。引用符をエスケープしないと、JSON のパース時にエラーになります。

無料の JSONL ツールをお試しください

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

よくある質問

参考資料