01.JSON コーディング規約

このドキュメントでは、JSON (JavaScript Object Notation) 形式のデータを記述する際のスタイルと規約を定めます。主に、APIのレスポンスや、設定ファイル（.json）での利用を想定しています。

Note

"共通原則との関係" 本規約は、01.共通コーディング原則の思想を、JSONデータ形式に適用するものです。

1. 基本フォーマット (Basic Format)

有効なJSON: 全てのJSONファイルは、JSONの公式仕様 (RFC 8259)に準拠した、文法的に正しい形式でなければなりません。コメントや末尾のカンマは許可されません。
文字エンコーディング: UTF-8を標準とします。

2. レイアウトと書式設定 (Layout and Formatting)

手作業でのスタイル遵守は非効率であり、レビューのノイズとなります。本プロジェクトでは、ツールによって規約の遵守を強制します。各ツールの設定は、リポジトリのルートに配置された .prettierrc.json ファイル（フォーマッター設定）および package.json ファイル（依存関係・スクリプト管理）で一元管理します。また、エディタレベルでの基本的な設定は .editorconfig ファイルで統一します。

フォーマッター: Prettier
- 役割: インデント、スペース、キーのクォーテーションなどを自動で統一します。手作業でのフォーマットは行わず、ツールに一任します。
- 運用: VSCodeなどのエディタで、JSONファイル保存時に自動で整形されるように設定してください。CI/CDプロセスにフォーマットチェックを組み込むことも有効です。

!!! success "CI/CDによる自動チェック" - GitHub Actionsのワークフローにprettier --check **/*.jsonを組み込むことで、JSONファイルのフォーマットが規約に違反しているコードのマージを自動的にブロックします。- VSCode拡張機能を導入し、ファイル保存時に自動でフォーマットが適用されるよう設定することを必須とします。

3. スタイルガイド (Style Guide)

Prettierによって自動整形される内容が主ですが、手動で記述する際の指針として以下を定めます。

インデント:
- 半角スペース2つを標準とします。
キー (Keys):
- 全てのキーは、ダブルクォーテーション (") で囲みます。
- キーの命名規則は、camelCase (キャメルケース) を標準とします。これは、多くのクライアントサイド言語（JavaScript/TypeScript）との親和性が高いためです。
```
// 良い例
{
    "userName": "Taro Yamada",
    "lastLoginAt": "2025-07-16T15:00:00Z"
}

// 悪い例 (snake_case)
// {
//   "user_name": "Taro Yamada"
// }
```
値 (Values):
- 文字列: ダブルクォーテーション (") で囲みます。シングルクォーテーション (') は使用できません。
- 数値、ブーリアン、null: クォーテーションで囲みません。
末尾のカンマ (Trailing Commas):
- オブジェクトの最後の要素や、配列の最後の要素の後にカンマを付けることは、JSONの仕様で許可されていません。
```
// 悪い例
// {
//   "key": "value",  // <-- このカンマはNG
// }
```

4. 設計上の考慮事項 (Design Considerations)

日時の形式:
- 日時を表す文字列は、原則としてISO 8601形式（例: "2025-07-16T15:00:00.000Z"）に統一します。タイムゾーンを含むZ（UTCを示す）を付与することを強く推奨します。
nullの扱い:
- 存在しない、または未設定の値を明確に示すために、キー自体を省略するのではなく、値としてnullを設定することを基本とします。
APIレスポンスの構造:
- APIのレスポンスボディは、将来的な拡張性（ページネーション情報など）を考慮し、ルートをオブジェクトとすることを推奨します。
```
// 良い例: 拡張しやすい
{
  "data": [ ... ],
  "totalCount": 100
}

// 悪い例: ルートが配列だと、後からメタデータを追加できない
// [ ... ]
```