オブジェクトと配列

実際の JSON ドキュメントの多くは、オブジェクトと配列を組み合わせてエンティティとコレクションを表します。明確な形を設計すると、API と設定の利用が楽になります。

オブジェクトをレコードとして

オブジェクトは多くの場合1 つのもの — ユーザー、注文、設定ブロック — を表します。

{
  "userId": "u_42",
  "email": "[email protected]",
  "preferences": {
    "theme": "dark",
    "notifications": true
  }
}

ネストしたオブジェクトは、関連フィールドを preferences_theme のようにフラット化せずにグループ化します。

配列をリストとして

配列は順序付きコレクション — タグ、明細行、検索結果 — を表します。

{
  "tags": ["json", "api", "tutorial"],
  "items": [
    { "sku": "A1", "qty": 2 },
    { "sku": "B3", "qty": 1 }
  ]
}

キー命名の慣習

JSON のキーは大文字小文字を区別します。よく使われるスタイル:

• camelCase — firstName（JavaScript API で一般的）
• snake_case — first_name（Python/Ruby バックエンドで一般的）
• kebab-case — キー内では - がマイナス記号になるため稀。多くの場合避ける

API ごとに 1 つのスタイルを選び、一貫して使いましょう。

空の構造

どちらも有効で、意味は異なります。

{ "list": [] }
{ "list": {} }

[] は空の配列、{} は空のオブジェクトです。スキーマが両方を許可しない限り、互いに置き換えないでください。

深さと可読性

深いネスト（a.b.c.d.e）はデータを反映しますが可読性を損ないます。多くのチームは明確なキー名でフラット化するか、大きな配列をページ分割します。馴染みのない JSON を読むときは、トップレベルから始め、オブジェクトまたは配列を 1 つずつ展開し、繰り返しパターンに注目してください — 多くの API payload はそう設計されています。