01.JSON コーディング規約
このドキュメントでは、JSON (JavaScript Object Notation) 形式のデータを記述する際のスタイルと規約を定めます。
主に、APIのレスポンスや、設定ファイル(.json
)での利用を想定しています。
共通原則との関係
本規約は、01.共通コーディング原則の思想を、JSONデータ形式に適用するものです。
1. 基本フォーマット
- 有効なJSON: 全てのJSONファイルは、JSONの公式仕様 (RFC 8259)に準拠した、文法的に正しい形式でなければなりません。
- 文字エンコーディング: UTF-8を標準とします。
2. スタイルガイド
一貫性と可読性を保つため、以下のスタイルを推奨します。
- インデント:
- 半角スペース2つを標準とします。
- タブ文字は使用しないでください。
- キー (Keys):
- 全てのキーは、ダブルクォーテーション (
"
) で囲みます。 - キーの命名規則は、
camelCase
(キャメルケース) を標準とします。これは、多くのクライアントサイド言語(JavaScript/TypeScript)との親和性が高いためです。// 良い例 { "userName": "Taro Yamada", "lastLoginAt": "2025-06-16T15:00:00Z" } // 悪い例 (snake_case) { "user_name": "Taro Yamada" }
- 全てのキーは、ダブルクォーテーション (
- 値 (Values):
- 文字列: ダブルクォーテーション (
"
) で囲みます。シングルクォーテーション ('
) は使用できません。 - 数値、ブーリアン、
null
: クォーテーションで囲みません。
- 文字列: ダブルクォーテーション (
- 末尾のカンマ (Trailing Commas):
- オブジェクトの最後の要素や、配列の最後の要素の後にカンマを付けることは、JSONの仕様で許可されていません。
// 悪い例 { "key": "value", // <-- このカンマはNG }
- オブジェクトの最後の要素や、配列の最後の要素の後にカンマを付けることは、JSONの仕様で許可されていません。
3. 自動フォーマットとリンティング
- 手作業でのフォーマットはミスを招くため、
Prettier
のような自動フォーマッターの利用を強く推奨します。 - VSCodeなどのエディタで、JSONファイル保存時に自動で整形されるように設定してください。
- CI/CDプロセスに、JSONファイルのフォーマットチェックや文法チェックを組み込むことも有効です。
4. 設計上の考慮事項
- 日時の形式:
- 日時を表す文字列は、原則としてISO 8601形式(例:
"2025-06-16T15:00:00.000Z"
)に統一します。タイムゾーンを含むZ
(UTCを示す)を付与することを強く推奨します。
- 日時を表す文字列は、原則としてISO 8601形式(例:
null
の扱い:- 存在しない、または未設定の値を明確に示すために、キー自体を省略するのではなく、値として
null
を設定することを基本とします。
- 存在しない、または未設定の値を明確に示すために、キー自体を省略するのではなく、値として
- APIレスポンスの構造:
- APIのレスポンスボディは、将来的な拡張性を考慮し、ルートをオブジェクトとすることを推奨します。
// 良い例: 拡張しやすい { "data": [ ... ], "totalCount": 100 } // 悪い例: ルートが配列だと、後からメタデータを追加できない [ ... ]
- APIのレスポンスボディは、将来的な拡張性を考慮し、ルートをオブジェクトとすることを推奨します。