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)) # => <class> (custom_decoderで変換されなかった)
</class>

--- デコード結果 (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}' が見つかりません。")

• 設定ファイル:
  アプリケーションの設定情報（データベース接続情報、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 ドキュメント