コンテンツにスキップ

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
      }
      

3. 自動フォーマットとリンティング

  • 手作業でのフォーマットはミスを招くため、Prettierのような自動フォーマッターの利用を強く推奨します。
  • VSCodeなどのエディタで、JSONファイル保存時に自動で整形されるように設定してください。
  • CI/CDプロセスに、JSONファイルのフォーマットチェックや文法チェックを組み込むことも有効です。

4. 設計上の考慮事項

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