著者: Jerry Fan

JSONL のベストプラクティス

品質と信頼性が高く、効率よく処理できる JSONL ファイルを作成するための総合ガイドです。書式のルール、スキーマ設計、エラー処理の方針、本番環境での処理を最適化する手法を解説します。

JSONL でベストプラクティスが重要な理由

JSONL(JSON Lines)は、1 行に 1 つの JSON オブジェクトを記述し、改行で区切るという、一見シンプルな形式です。ただし、シンプルだからといって、問題が起きないわけではありません。スキーマの不統一、エンコーディングの問題、末尾のカンマ、文字列内の改行は、本番のデータパイプラインでパースエラーを引き起こす代表的な原因です。明確なベストプラクティスに従うことで、こうした問題を未然に防げます。

このガイドでは、JSONL データを確実に生成・処理するための基本ルールを解説します。機械学習用データセットの作成、アプリケーションログのストリーミング処理、サービス間のデータ交換など、さまざまな場面で、見落としやすいバグを防ぎ、JSONL を扱うワークフローのパフォーマンスを向上させるのに役立ちます。

書式のルール

正しい JSONL ファイルを作成するには、いくつかの書式ルールを厳密に守る必要があります。どれか 1 つでも守られていないと、ほとんどのパーサーで読み込めないファイルになります。

JSONL ファイルの各行は、その行だけで完結する、完全な JSON 値である必要があります。1 つの JSON オブジェクトを複数行に分けてはいけません。改行やインデントを付けて整形した JSON は、有効な JSONL にはなりません。必ずコンパクトな形式でシリアライズし、インデントやキーと値の間の余分な空白を入れないでください。

1 行に 1 つの JSON オブジェクトを記述する
# Valid JSONL - one complete JSON per line
{"id":1,"name":"Alice","tags":["admin","user"]}
{"id":2,"name":"Bob","tags":["user"]}


# INVALID - pretty-printed JSON spans multiple lines
{
  "id": 1,
  "name": "Alice"
}

JSONL ファイルは UTF-8 でエンコードする必要があります。これは事実上すべての JSONL パーサー、ストリーミングツール、クラウドサービスが想定するエンコーディングです。UTF-16、Latin-1、その他のエンコーディングは避けてください。ソースデータが異なるエンコーディングを使用している場合は、JSONL を書き込む前に UTF-8 に変換してください。

エンコーディングは必ず UTF-8 にする
# Python: always specify UTF-8 when reading/writing
with open('data.jsonl', 'w', encoding='utf-8') as f:
    f.write(json.dumps(record, ensure_ascii=False) + '\n')


# Node.js: UTF-8 is the default for fs
fs.appendFileSync('data.jsonl', JSON.stringify(record) + '\n', 'utf-8');

行の区切りには、LF(\n)を 1 文字使います。Linux、macOS、ほとんどのクラウド環境では、これが標準です。Windows で使われる CRLF(キャリッジリターン + ラインフィード、\r\n)は、パース時に問題を起こす可能性があるため避けてください。最近のエディタやツールの多くは改行コードを自動で処理しますが、複数の OS で作業する場合は設定を確認してください。

改行コードを選ぶ
# Correct: LF line endings (\n)
{"id":1}\n{"id":2}\n


# Avoid: CRLF line endings (\r\n)
{"id":1}\r\n{"id":2}\r\n


# Tip: configure Git to normalize line endings
# .gitattributes
*.jsonl text eol=lf

スキーマの一貫性

JSONL 自体はスキーマを強制しませんが、レコード間でスキーマを統一すると、データを格段に扱いやすくなります。スキーマが不統一だと、実行時エラーや想定外の null 値、インポートの失敗につながります。

すべてのレコードで、フィールド名、フィールドの順序、値の型を揃えてください。JSON ではフィールドの順序に決まりはありませんが、順序を統一すると可読性と圧縮率が向上します。同じフィールドに異なる型を混在させてはいけません。たとえば、price フィールドの値が、あるレコードでは文字列、別のレコードでは数値になるような状態は避けてください。

フィールド名・順序・型を統一する
# Good: consistent field order and types
{"id":1,"name":"Alice","age":30,"active":true}
{"id":2,"name":"Bob","age":25,"active":false}
{"id":3,"name":"Charlie","age":35,"active":true}


# Bad: inconsistent order, mixed types, missing fields
{"name":"Alice","id":1,"active":true}
{"id":"2","age":25,"name":"Bob"}
{"id":3,"active":"yes","name":"Charlie"}

フィールドに値がない場合は、キー自体を省略せず、JSON の null を値として設定してください。すべてのレコードでキーが揃うため、後続の処理がシンプルになります。データを読み取る側も、「フィールドが存在しない場合」と「フィールドの値が null の場合」を区別する必要がなくなります。

欠損値は null で明示する
# Good: include all fields, use null for missing values
{"id":1,"name":"Alice","email":"[email protected]","phone":null}
{"id":2,"name":"Bob","email":null,"phone":"+1-555-0100"}


# Avoid: omitting keys for missing data
{"id":1,"name":"Alice","email":"[email protected]"}
{"id":2,"name":"Bob","phone":"+1-555-0100"}

エラー処理

実際に扱う JSONL ファイルには、エンコーディングの不具合、書き込みの中断、上流のバグなどにより、不正な行が少数含まれていることがよくあります。堅牢な読み取り処理では、最初の不正な行で異常終了せず、こうした行を適切に扱います。

各行をパースする処理を try-catch ブロックで囲み、失敗した場合は行番号とエラーメッセージをログに記録します。これにより、問題の内容を記録に残しながら、不正な行をスキップできます。重要なパイプラインでは、後から確認できるよう、不正な行を別のファイルにまとめて保存してください。

エラーのある行を記録しながらパースを続ける
import json


def parse_jsonl_safe(path: str):
    """Parse JSONL with error tolerance."""
    valid, errors = [], []
    with open(path, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            try:
                valid.append(json.loads(line))
            except json.JSONDecodeError as e:
                errors.append({'line': line_num, 'error': str(e), 'raw': line})
    print(f'Parsed {len(valid)} records, {len(errors)} errors')
    return valid, errors

データパイプラインでは、主処理の前に検証ステップを設けてください。各レコードに必要なフィールドがあり、値が想定どおりの型になっているかを確認します。条件に合わないレコードは受け付けないか、隔離してください。これにより、原因の特定が難しくなるパイプラインの後半での型エラーを防げます。

処理の前に検証する
def validate_record(record: dict) -> list[str]:
    """Validate a JSONL record against expected schema."""
    issues = []
    required = ['id', 'name', 'timestamp']
    for field in required:
        if field not in record:
            issues.append(f'Missing required field: {field}')
    if 'id' in record and not isinstance(record['id'], int):
        issues.append(f'Field "id" should be int, got {type(record["id"]).__name__}')
    return issues


# Usage in pipeline
for record in parse_jsonl_safe('data.jsonl')[0]:
    issues = validate_record(record)
    if issues:
        log_warning(f'Record {record.get("id")}: {issues}')
    else:
        process(record)

パフォーマンスの最適化

データエンジニアリングや機械学習のワークフローでは、JSONL ファイルが数 GB 規模になることもあります。適切な処理方法を選べば、メモリ使用量を抑えながら、高いスループットを維持できます。

JSONL ファイル全体を一度にメモリへ読み込んではいけません。1 行ずつ、または複数行をバッチにまとめて読み込み、処理してください。こうすることで、ファイルサイズにかかわらず、メモリ使用量を一定に保てます。Python ではファイルを反復処理すると 1 行ずつ読み込まれます。Node.js にも、同じ用途で使える readline や stream API があります。

ストリーミング処理
# Python: stream with constant memory
import json


count = 0
with open('large.jsonl', 'r', encoding='utf-8') as f:
    for line in f:  # One line at a time, not f.readlines()!
        record = json.loads(line)
        process(record)
        count += 1
print(f'Processed {count} records')

データベースへの書き込みや API 呼び出しでは、レコードを 1 件ずつ処理せず、複数件をバッチにまとめて処理してください。I/O のオーバーヘッドを減らせるため、スループットが 10〜100 倍に向上することがあります。多くの用途では、1 バッチあたり 1,000〜10,000 件が適切です。

バッチ処理
import json


def process_in_batches(path: str, batch_size: int = 5000):
    """Process JSONL records in batches for better throughput."""
    batch = []
    with open(path, 'r', encoding='utf-8') as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            batch.append(json.loads(line))
            if len(batch) >= batch_size:
                bulk_insert(batch)  # Send batch to database
                batch.clear()
    if batch:
        bulk_insert(batch)  # Flush remaining records

JSONL は隣接する行でキーが共通し、値も似ていることが多いため、非常によく圧縮できます。保存や転送には gzip を使い、ファイルサイズを 5〜10 分の 1 に削減してください。ほとんどの言語では、gzip 圧縮された JSONL を、事前にディスク上へ展開せずに直接読み込めます。

保存・転送時は圧縮する
import gzip
import json


# Write compressed JSONL
with gzip.open('data.jsonl.gz', 'wt', encoding='utf-8') as f:
    for record in records:
        f.write(json.dumps(record, ensure_ascii=False) + '\n')


# Read compressed JSONL
with gzip.open('data.jsonl.gz', 'rt', encoding='utf-8') as f:
    for line in f:
        record = json.loads(line)
        process(record)

避けたいよくある間違い

ここでは、当サイトのツールで JSONL ファイルを検証する際によく見られる問題を紹介します。いずれもパースエラーの原因となり、適切な方法で調べないと原因の特定が難しくなることがあります。

JSON では、オブジェクトや配列の最後の要素の後にカンマを付けることはできません。これは特によくある間違いの 1 つで、末尾のカンマが許される JavaScript に慣れた開発者は注意が必要です。出力には末尾のカンマを残さないようにしてください。

末尾のカンマ
# INVALID: trailing comma after last property
{"id": 1, "name": "Alice",}


# VALID: no trailing comma
{"id": 1, "name": "Alice"}


# INVALID: trailing comma in array
{"tags": ["admin", "user",]}


# VALID: no trailing comma in array
{"tags": ["admin", "user"]}

文字列の値に改行文字をそのまま含めると、1 行 1 レコードのルールが崩れ、JSONL ファイルが不正な形式になります。JSON 文字列内の改行は必ず \n とエスケープして表し、実際の改行を入れないでください。ほとんどの JSON シリアライザーは自動で処理しますが、JSON 文字列を手作業で組み立てる場合は注意が必要です。

文字列内の改行
# INVALID: raw newline inside a string value breaks JSONL
{"id": 1, "bio": "Line one
Line two"}


# VALID: escaped newline keeps everything on one line
{"id": 1, "bio": "Line one\nLine two"}


# Tip: json.dumps() in Python handles this automatically
import json
record = {"bio": "Line one\nLine two"}
print(json.dumps(record))
# Output: {"bio": "Line one\nLine two"}

同じファイル内に UTF-8 と Latin-1 などの異なるエンコーディングが混在すると、文字化けやパースエラーが発生します。異なるデータソースから追記する際によく起きる問題です。書き込む前に、必ず UTF-8 に統一してください。エンコーディングが不明なデータを受け取った場合は、chardet などのライブラリで判定してから変換してください。

エンコーディングの混在・誤り
# Python: detect and convert encoding
import chardet


def normalize_to_utf8(input_path: str, output_path: str):
    """Detect encoding and convert to UTF-8."""
    with open(input_path, 'rb') as f:
        raw = f.read()
    detected = chardet.detect(raw)
    encoding = detected['encoding'] or 'utf-8'
    print(f'Detected encoding: {encoding}')
    text = raw.decode(encoding)
    with open(output_path, 'w', encoding='utf-8') as f:
        f.write(text)

ファイルの命名と整理

ファイルの命名規則とディレクトリ構造を整えると、自動化されたパイプラインで JSONL データを見つけやすくなり、管理や処理も容易になります。

拡張子は、基本的に .jsonl を使ってください。JSON Lines ファイルの拡張子として最も広く認知されており、OpenAI のファインチューニング API や BigQuery をはじめ、多くのデータプラットフォームで使われています。.ndjson(Newline Delimited JSON)も、名前が異なるだけで、技術的には同じ形式です。どちらかに決めて、プロジェクト全体で統一してください。

拡張子 .jsonl と .ndjson の使い分け
# Recommended file naming conventions
data.jsonl              # Standard JSONL file
users_2026-02-14.jsonl  # Date-stamped export
train.jsonl             # ML training data
validation.jsonl        # ML validation split
events.jsonl.gz         # Compressed JSONL

JSONL ファイルは用途と日付で整理し、未加工の入力データと処理済みの出力データを分けて管理してください。時系列データやログデータは日付単位でパーティションを分けると、特定の期間のデータを処理したり、古いデータを削除したりしやすくなります。

JSONL プロジェクトのディレクトリ構造
project/
  data/
    raw/                  # Original unprocessed files
      events_2026-02-13.jsonl
      events_2026-02-14.jsonl
    processed/            # Cleaned and transformed
      events_clean.jsonl
    schemas/              # Schema documentation
      event_schema.json
  scripts/
    validate.py           # Validation script
    transform.py          # Transformation pipeline

今すぐ JSONL ファイルをチェック

最大 1GB の JSONL ファイルを、ブラウザ上で直接検証・整形できます。書式の誤り、スキーマの不整合、エンコーディングの問題をすぐに検出します。

よくある質問

参考資料