JSONフォーマットのベストプラクティス：構造・命名・スタイル
4 分で読了
適切にフォーマットされたJSONは読みやすく、デバッグしやすく、保守しやすくなります。以下のベストプラクティスはAPIレスポンス、設定ファイル、データストレージに適用されます。
命名
- 一貫したケースを使う（camelCaseまたはsnake_case）
- 説明的な名前にする：
createdAtであってcaではない - 配列には複数形を使う：
"items"であって"item"ではない - 略語を避ける：
organizationIdであってorgIdではない - ブール値には
is/hasプレフィックスを使う："isActive"、"hasPermission"
構造
- 3階層以上のネストを避ける
- 順序付きコレクションには配列を、キーバリューデータにはオブジェクトを使う
- オプションのフィールドが欠落している場合は
nullを含める（省略しない） - 日付にはISO 8601形式を使う：
"2026-06-01T00:00:00Z" - 列挙型には文字列を使う：
"status": "active"は"status": 1より明確
スタイル
- 開発環境ではプリティプリント（2スペースインデント）でデバッグしやすくする
- 本番APIでは帯域を節約するためミニファイする
- 末尾のカンマを避ける（JSONでは無効）
- コメントはサポートされない — メタデータフィールドを使う
良い例 vs 悪い例
| 悪い例 | 良い例 | 理由 |
|---|---|---|
{"ca": "2026-01-01"} | {"createdAt": "2026-01-01T00:00:00Z"} | 説明的な名前 + ISO 8601 |
{"item": [...]} | {"items": [...]} | 配列には複数形 |
{"status": 1} | {"status": "active"} | 文字列列挙型の方が明確 |
{"userId": 1, "user_name": "A"} | {"userId": 1, "userName": "A"} | ケースの一貫性 |