Python で JSON を扱う実践ガイド：読み書き・検証・変換

Python 標準の json モジュールは、API サンプル、設定ファイル、データ変換の多くを処理できます。実務では、エンコーディング、エラー位置、数値精度、入力構造を明示することが重要です。

解析エラーの位置を残す

import json

raw = '{"name": "Ada", "active": true}'

try:
    data = json.loads(raw)
except json.JSONDecodeError as exc:
    print(f"Invalid JSON: line {exc.lineno}, column {exc.colno}: {exc.msg}")
    raise

完全なペイロードをログへ出すと秘密情報が漏れる可能性があります。行・列、リクエスト ID、短い説明だけを記録してください。

UTF-8 でファイルを読み書きする

import json
from pathlib import Path

source = Path("input.json")
target = Path("output.json")

with source.open("r", encoding="utf-8") as handle:
    data = json.load(handle)

with target.open("w", encoding="utf-8") as handle:
    json.dump(data, handle, ensure_ascii=False, indent=2)
    handle.write("\n")

重要な設定ファイルは一時ファイルへ書き、成功後に置き換えると途中で壊れにくくなります。

必要な場合は10進精度を保つ

import json
from decimal import Decimal

payload = json.loads('{"amount": 19.99}', parse_float=Decimal)
print(payload["amount"] * 3)

Decimal はそのままでは JSON に書き戻せません。契約が10進文字列を使うのか、最小通貨単位の整数を使うのかを決め、明示的に変換します。

変換前に構造を確認する

def normalize_users(value):
    if not isinstance(value, list):
        raise ValueError("Root must be an array")

    result = []
    for index, item in enumerate(value):
        if not isinstance(item, dict):
            raise ValueError(f"Item {index} must be an object")
        if "id" not in item or "email" not in item:
            raise ValueError(f"Item {index} is missing id or email")
        result.append({
            "id": str(item["id"]),
            "email": str(item["email"]).strip().lower(),
        })
    return result

複雑な契約には JSON Schema と保守されている検証ライブラリを使います。構文検証と契約検証は別の問題です。

変換ルールを明示する

ネストした JSON を CSV や DB 行へ変換する場合、配列、欠落、null をどう表すか決めてください。

def order_row(order):
    customer = order.get("customer") or {}
    return {
        "order_id": order.get("id"),
        "customer_email": customer.get("email"),
        "item_count": len(order.get("items") or []),
        "status": order.get("status", "unknown"),
    }

入力と期待出力をテストとして保存すると、変換時の判断を後から確認できます。

コマンドラインで確認する

python -m json.tool input.json
python -m json.tool --sort-keys input.json

視覚的に確認する場合は JSON Beautifier や JSON Tree Viewer も利用できます。不要な秘密情報は事前に除去してください。

本番前チェック

• • UTF-8 を明示する。

• • 入力サイズとネスト深度を制限する。

• • 欠落と明示的な null を区別する。

• • 精度が必要な数値は Decimal、文字列、最小単位整数で扱う。

• • 変換前に構造を検証する。

• • 空配列、Unicode、大整数、不正 JSON をテストする。

全オプションは Python 公式の json ドキュメントで確認できます。まず標準ライブラリを使い、契約に必要なときだけ Schema 検証を追加しましょう。