Python標準ライブラリ「json」徹底解説：データ交換の要をマスターしよう！

はじめに：JSONとは何か？なぜ重要か？

JSON（JavaScript Object Notation）は、軽量なデータ交換フォーマットであり、現代のウェブ開発やAPI連携において不可欠な存在です。人間にとって読み書きが容易であり、同時にコンピュータにとっても解析や生成がしやすいという特徴を持っています。

もともとはJavaScriptのオブジェクトリテラル記法に由来しますが、特定のプログラミング言語に依存せず、Python、Java、Ruby、PHPなど、多くの言語で広くサポートされています。主に以下のような場面で活躍します。

• Web API（サーバーとクライアント間のデータ通信）
• 設定ファイル（アプリケーションの設定情報を記述）
• 異なるシステム間のデータ交換
• ドキュメント指向データベースでのデータ格納

Pythonには、このJSONデータを簡単に扱うための強力な標準ライブラリ json が組み込まれています。追加のインストールは不要で、インポートするだけで利用可能です。このライブラリを使えば、Pythonのオブジェクト（辞書やリストなど）をJSON形式の文字列やファイルに変換（シリアライズまたはエンコード）したり、逆にJSON形式の文字列やファイルをPythonオブジェクトに変換（デシリアライズまたはデコード）したりすることができます。

このブログ記事では、Pythonの json ライブラリの基本的な使い方から、少し応用的なテクニックまで、具体的なコード例を交えながら詳しく解説していきます。さあ、データ交換の要となるJSONの世界をPythonで探求しましょう！

import json

上記のコードで json モジュールをインポートすれば、準備完了です！

主要な関数：シリアライズとデシリアライズ

json モジュールには、主に4つの重要な関数があります。これらは、PythonオブジェクトとJSONデータ（文字列またはファイル）を相互に変換する役割を担います。

import json

python_dict = {
    "name": "山田 太郎",
    "age": 30,
    "isStudent": False,
    "courses": ["Python", "データサイエンス"],
    "address": {
        "city": "東京都",
        "zip": "100-0001"
    },
    "score": None
}

# Python辞書をJSON文字列に変換
json_string = json.dumps(python_dict, ensure_ascii=False, indent=4, sort_keys=True)

print("--- JSON 文字列 ---")
print(json_string)
print("\n--- 型 ---")
print(type(json_string))

--- JSON 文字列 ---
{
    "address": {
        "city": "東京都",
        "zip": "100-0001"
    },
    "age": 30,
    "courses": [
        "Python",
        "データサイエンス"
    ],
    "isStudent": false,
    "name": "山田 太郎",
    "score": null
}

--- 型 ---
<class 'str'>

import json

json_string = """
{
    "name": "鈴木 花子",
    "age": 25,
    "city": "大阪市",
    "hobbies": ["読書", "旅行"],
    "isActive": true,
    "score": null
}
"""

# JSON文字列をPythonオブジェクト (辞書) に変換
python_obj = json.loads(json_string)

print("--- Python オブジェクト ---")
print(python_obj)
print("\n--- 型 ---")
print(type(python_obj))
print("\n--- アクセス例 ---")
print(f"名前: {python_obj['name']}")
print(f"趣味の1つ目: {python_obj['hobbies'][0]}")

--- Python オブジェクト ---
{'name': '鈴木 花子', 'age': 25, 'city': '大阪市', 'hobbies': ['読書', '旅行'], 'isActive': True, 'score': None}

--- 型 ---
<class 'dict'>

--- アクセス例 ---
名前: 鈴木 花子
趣味の1つ目: 読書

import json

python_data = {
    "product_id": "P12345",
    "name": "高性能ノートPC",
    "price": 150000,
    "in_stock": True,
    "specs": {
        "cpu": "Core i7",
        "ram_gb": 16,
        "storage_gb": 512
    },
    "tags": ["PC", "高性能", "テレワーク"]
}

file_path = 'product_data.json'

# ファイルに書き込みモード ('w') でオープンし、エンコーディングをUTF-8に指定
# ensure_ascii=False と併用する場合、UTF-8指定が重要
with open(file_path, 'w', encoding='utf-8') as f:
    # PythonオブジェクトをファイルにJSON形式で書き込む
    json.dump(python_data, f, ensure_ascii=False, indent=2)

print(f"データが '{file_path}' に書き込まれました。")

# 書き込まれた内容を確認 (オプション)
with open(file_path, 'r', encoding='utf-8') as f:
    print("\n--- ファイルの内容 ---")
    print(f.read())

import json

file_path = 'product_data.json' # 先ほど dump() で作成したファイル

# ファイルを読み込みモード ('r') でオープンし、エンコーディングをUTF-8に指定
try:
    with open(file_path, 'r', encoding='utf-8') as f:
        # ファイルからJSONデータを読み込み、Pythonオブジェクトに変換
        loaded_data = json.load(f)

    print("--- 読み込んだPythonオブジェクト ---")
    print(loaded_data)
    print("\n--- 型 ---")
    print(type(loaded_data))
    print("\n--- アクセス例 ---")
    print(f"商品名: {loaded_data['name']}")
    print(f"価格: {loaded_data['price']}")
    print(f"スペック(CPU): {loaded_data['specs']['cpu']}")

except FileNotFoundError:
    print(f"エラー: ファイル '{file_path}' が見つかりません。")
except json.JSONDecodeError as e:
    print(f"エラー: JSONファイルの形式が正しくありません。詳細: {e}")
except Exception as e:
    print(f"予期せぬエラーが発生しました: {e}")

データ型の対応関係

PythonのオブジェクトとJSONの間でデータを変換する際、データ型は以下のように対応付けられます。

カスタムオブジェクトの扱い

デフォルトでは、Pythonの標準的なデータ型（辞書、リスト、文字列、数値、真偽値、None）しかJSONにシリアライズできません。自作のクラスのインスタンスなどを直接 json.dumps() や json.dump() に渡すと TypeError が発生します。

import json
from datetime import datetime

class User:
    def __init__(self, name, registered_at):
        self.name = name
        self.registered_at = registered_at

user = User("Alice", datetime(2024, 4, 1, 12, 30, 0))

try:
    json_string = json.dumps(user, indent=2)
    print(json_string)
except TypeError as e:
    print(f"シリアライズエラー: {e}") # => シリアライズエラー: Object of type User is not JSON serializable

これを解決するには、カスタムエンコーダ/デコーダを定義する必要があります。

import json
from datetime import datetime, date

class User:
    def __init__(self, name, registered_at):
        self.name = name
        self.registered_at = registered_at # datetimeオブジェクト

def custom_serializer(obj):
    if isinstance(obj, (datetime, date)):
        # datetimeオブジェクトやdateオブジェクトはISO 8601形式の文字列に変換
        return obj.isoformat()
    elif isinstance(obj, User):
        # Userオブジェクトは辞書に変換
        return {
            "name": obj.name,
            "registered_at": obj.registered_at.isoformat(), # datetimeも変換
            "_custom_type": "User" # デコード時に型を識別するための情報 (オプション)
        }
    # 他のシリアライズ不可能な型があればここに追加
    raise TypeError(f"Object of type {obj.__class__.__name__} is not JSON serializable")

user = User("Bob", datetime(2024, 4, 2, 9, 0, 0))

# default引数に関数を指定
json_string = json.dumps(user, default=custom_serializer, indent=2, ensure_ascii=False)
print("--- Userオブジェクト (default使用) ---")
print(json_string)

# datetimeオブジェクト単体でも変換可能
now = datetime.now()
json_datetime = json.dumps(now, default=custom_serializer)
print("\n--- datetimeオブジェクト (default使用) ---")
print(json_datetime) # 例: "2025-04-02T06:31:12.123456" (ISO 8601形式)

--- Userオブジェクト (default使用) ---
{
  "name": "Bob",
  "registered_at": "2024-04-02T09:00:00",
  "_custom_type": "User"
}

--- datetimeオブジェクト (default使用) ---
"2025-04-02T06:31:12.123456"

import json
from datetime import datetime, date

class User: # 再掲
    def __init__(self, name, registered_at):
        self.name = name
        self.registered_at = registered_at

class CustomEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, (datetime, date)):
            return obj.isoformat()
        elif isinstance(obj, User):
            return {
                "name": obj.name,
                "registered_at": obj.registered_at.isoformat(),
                "_custom_type": "User" # デコード用
            }
        # 他の型が必要なら追加
        # 親クラスのdefaultを呼び出してデフォルトのTypeErrorを発生させる
        return super().default(obj)

user = User("Charlie", datetime(2024, 1, 1, 0, 0, 0))

# cls引数にカスタムエンコーダークラスを指定
json_string = json.dumps(user, cls=CustomEncoder, indent=2, ensure_ascii=False)
print("--- Userオブジェクト (カスタムEncoder使用) ---")
print(json_string)

--- Userオブジェクト (カスタムEncoder使用) ---
{
  "name": "Charlie",
  "registered_at": "2024-01-01T00:00:00",
  "_custom_type": "User"
}

import json
from datetime import datetime

class User: # 再掲
    def __init__(self, name, registered_at):
        self.name = name
        self.registered_at = registered_at

    def __repr__(self): # 表示用
        return f"User(name='{self.name}', registered_at={self.registered_at!r})"

def custom_decoder(dct):
    # エンコード時に付与した識別子をチェック
    if "_custom_type" in dct and dct["_custom_type"] == "User":
        # Userオブジェクトを再構築
        # datetime文字列もdatetimeオブジェクトに変換
        return User(dct["name"], datetime.fromisoformat(dct["registered_at"]))
    # 他のカスタム型があればここに追加
    # datetime文字列単体などを変換したい場合は、キーが存在するかなどで判定
    if "registered_at" in dct and isinstance(dct["registered_at"], str):
         try:
             # ISOフォーマットならdatetimeに変換してみる (これはUserの場合と被るので注意が必要)
             # より堅牢にするには、専用のキーを用意するなど工夫が必要
             # ここでは単純化のためコメントアウト
             # dct["registered_at"] = datetime.fromisoformat(dct["registered_at"])
             pass
         except ValueError:
             pass # 変換できなければそのまま
    return dct # マッチしなければ元の辞書を返す

json_string_user = """
{
  "name": "David",
  "registered_at": "2023-12-25T10:30:00",
  "_custom_type": "User"
}
"""

json_string_other = """
{
  "item_id": 101,
  "description": "通常の辞書データ"
}
"""

# object_hookに関数を指定してデコード
user_obj = json.loads(json_string_user, object_hook=custom_decoder)
other_obj = json.loads(json_string_other, object_hook=custom_decoder)

print("--- デコード結果 (User) ---")
print(user_obj)
print(type(user_obj))
print(f"登録日時オブジェクトの型: {type(user_obj.registered_at)}")

print("\n--- デコード結果 (Other) ---")
print(other_obj)
print(type(other_obj)) # =>  (custom_decoderで変換されなかった)

--- デコード結果 (User) ---
User(name='David', registered_at=datetime.datetime(2023, 12, 25, 10, 30))
<class '__main__.User'>
登録日時オブジェクトの型: <class 'datetime.datetime'>

--- デコード結果 (Other) ---
{'item_id': 101, 'description': '通常の辞書データ'}
<class 'dict'>

高度な使い方とヒント

import json

invalid_json_string = '{"name": "Alice", "age": 30,}' # 末尾に余分なカンマ

try:
    data = json.loads(invalid_json_string)
    print(data)
except json.JSONDecodeError as e:
    print(f"JSONデコードエラーが発生しました！")
    print(f"エラーメッセージ: {e.msg}")
    print(f"エラー発生箇所 (行): {e.lineno}")
    print(f"エラー発生箇所 (列): {e.colno}")
    # print(f"エラー箇所周辺のドキュメント: {e.doc[e.pos-10:e.pos+10]}") # エラー箇所周辺の確認
except Exception as e:
    print(f"予期せぬエラー: {e}")

JSONデコードエラーが発生しました！
エラーメッセージ: Expecting property name enclosed in double quotes
エラー発生箇所 (行): 1
エラー発生箇所 (列): 29

import json

json_string = '{"name": "Bob"}' # age キーが存在しない

try:
    data = json.loads(json_string)
    print(f"Name: {data['name']}")
    # 存在しないキーにアクセスしようとすると KeyError が発生
    print(f"Age: {data['age']}")
except json.JSONDecodeError as e:
    print(f"JSONデコードエラー: {e}")
except KeyError as e:
    print(f"キーエラー: キー '{e}' が見つかりません。")
except Exception as e:
    print(f"予期せぬエラー: {e}")

Name: Bob
キーエラー: キー 'age' が見つかりません。

# Linux/macOS
cat data.json | python -m json.tool

# Windows (PowerShell)
Get-Content data.json | python -m json.tool

cat data.json | python -m json.tool --sort-keys

ユースケース：どんな時に使う？

Pythonの json ライブラリは、様々な場面で活用されています。

• Web APIとの連携:
  現代のWebサービスの多くは、データをJSON形式で送受信するAPIを提供しています。Pythonの requests ライブラリなどを使ってAPIからデータを取得し、json.loads() (または response.json() メソッド) でPythonオブジェクトに変換して利用したり、逆にPythonで作成したデータを json.dumps() でJSON文字列に変換してAPIに送信したりします。

  import requests
  import json
  
  # 例: OpenWeatherMap API (架空のAPIキー)
  api_key = "YOUR_API_KEY"
  city = "Tokyo"
  url = f"https://api.openweathermap.org/data/2.5/weather?q={city}&appid={api_key}&units=metric⟨=ja"
  
  try:
      response = requests.get(url)
      response.raise_for_status() # ステータスコードが200番台以外なら例外発生
  
      # requests の .json() メソッドは内部で json.loads() を呼んでいる
      weather_data = response.json()
  
      print(f"{weather_data['name']}の天気:")
      print(f"- 天気: {weather_data['weather'][0]['description']}")
      print(f"- 気温: {weather_data['main']['temp']}℃")
      print(f"- 湿度: {weather_data['main']['humidity']}%")
  
  except requests.exceptions.RequestException as e:
      print(f"APIリクエストエラー: {e}")
  except json.JSONDecodeError:
      print("APIレスポンスのJSON形式が不正です。")
  except KeyError as e:
      print(f"レスポンスに必要なキー '{e}' が見つかりません。")
  

  Copy
• 設定ファイル:
  アプリケーションの設定情報（データベース接続情報、APIキー、各種パラメータなど）をJSONファイルに記述し、起動時に json.load() で読み込んで利用する、といった使い方が一般的です。JSONは人間が読み書きしやすいため、設定ファイルの形式として適しています。
• データの保存・交換:
  プログラムの処理結果や中間データを、一時的または永続的にファイルに保存する際にJSON形式が使われます。異なるプログラミング言語やシステム間でデータをやり取りする場合にも、JSONの汎用性の高さが活かされます。
• ログデータ:
  構造化されたログデータをJSON形式で出力することがあります。これにより、ログ解析ツールでの処理が容易になります。

まとめ

Pythonの標準ライブラリ json は、現代のデータ駆動型アプリケーション開発において非常に重要で便利なツールです。この記事では、以下の主要な機能と使い方を解説しました。

• 基本的な変換: dumps(), loads(), dump(), load() を使ったPythonオブジェクトとJSON文字列/ファイルの相互変換。
• データ型の対応: PythonとJSON間でのデータ型マッピング。
• 整形とオプション: indent, sort_keys, ensure_ascii などの便利な引数。
• カスタムオブジェクトの処理: default 引数や JSONEncoder サブクラスによるカスタムシリアライズ、object_hook や JSONDecoder サブクラスによるカスタムデシリアライズ。
• エラーハンドリング: JSONDecodeError の捕捉。
• 応用: パフォーマンスに関するヒントやコマンドラインツールの紹介。
• ユースケース: API連携、設定ファイル、データ交換など。

json モジュールを使いこなすことで、Pythonでのデータ処理の幅が大きく広がります。ぜひ、実際のプロジェクトで活用してみてください！

さらに詳しい情報が必要な場合は、Pythonの公式ドキュメントを参照することをお勧めします。
json — JSON エンコーダおよびデコーダ — Python ドキュメント