JSON の配列とオブジェクトの書き方:構造とネスト入門
要点:JSON に存在する二つのコンテナを一気に整理します。オブジェクトはフィールド、配列はリストを担当し、ネストの組み合わせ方、どちらをいつ使うか、数値キーの偽配列・末尾カンマ・シングルクォートという三大ミスの直し方まで解説します。

JSON が用意しているコンテナは二つだけです。オブジェクトは「名前の付いたフィールド」を、配列は「順序付きのリスト」を担当します。書き方を間違える原因の九割は、クォートとカンマ、そしてリストを偽オブジェクトとして書いてしまうことにあります。
一、JSON にあるコンテナは二つだけ
API がどれほど複雑なデータを返してきても、分解していけば最後は二つのコンテナと六種類の値に行き着きます。オブジェクト(object)は「キーと値のペア」の集まりで、波括弧 {} で包みます。配列(array)は順序付きの値の並びで、角括弧 [] で包みます。値には文字列、数値、true/false、null が書け、さらにオブジェクトや配列をネストすることもできます。オブジェクトの中に配列、配列の中にオブジェクト——この組み合わせだけで、現実のすべてのデータが表現されています。
{
"user": { "name": "Ada", "active": true },
"roles": ["admin", "editor"],
"lastLogin": null,
"loginCount": 42
}
この認識は実務で効きます。読み解けない JSON に遭遇したとき、最初の文字から順に読むのではなく、最も外側が { か [ かを先に確認してください。オブジェクトならフィールドとして、配列ならリストとして読み、一層ずつ中へ降りていけば構造が掴めます。json.org の文法図が一枚に収まっているのはまさにこのためで、二つの構造と再帰的なネストだけで表現力は十分だからです。
二、オブジェクトの書き方:四つの厳格ルール
オブジェクトは初心者のエラーが最も集中する場所ですが、ルールは実質四つしかありません。
- キーは必ずダブルクォートの文字列。
{name: "Ada"}も{'name': 'Ada'}も不正で、{"name": "Ada"}と書く必要があります。JavaScript のオブジェクトリテラルは裸のキーやシングルクォートを許しますが、JSON は許しません。これが両者を混同する最大のポイントです。 - ペア同士はカンマで区切り、最後のペアの後ろにカンマを置かない。
{"a": 1, "b": 2,}は閉じ波括弧の位置でUnexpected token }を出します。 - キーは一意であるべき。RFC 8259 は MUST ではなく SHOULD と書いており、重複キーはエラーになりません。しかし最初の値を取るか最後の値を取るかはパーサーの実装次第で、言語ごとに結果が異なることがあるため、依存してはいけません。
- キーの順序に意味はない。
{"a":1,"b":2}と{"b":2,"a":1}は同じオブジェクトです。diff ツールも比較関数もキー順を無視します。順序が必要なデータは配列に入れるべきものです。
三、配列の書き方:順序そのものがデータ
配列は位置で値を格納し、インデックスは 0 から始まります。["admin", "editor"] の "editor" は [1] です。「順序に意味がある」ことが配列とオブジェクトの本質的な違いです。検索結果の関連度順、操作ログの時系列——こうした情報は順序の中にだけ存在しており、オブジェクトに置き換えた瞬間に失われます。
実用的な助言を二つ。第一に、配列の要素はできるだけ同型に揃えます。[{"id":1},{"id":2}] は [1, "text", true] よりはるかに扱いやすく、後者は文法上正しいものの、消費側のコードは毎ステップ型分岐を書かされます。第二に、空配列 [] は完全に合法な値です。リスト系のフィールドにまだ中身がないときは null ではなく [] を返すと、消費側は「存在するか」の確認と「空か」の確認を一度に済ませられます。
[
{ "city": "Tokyo", "population": 13960000 },
{ "city": "Delhi", "population": 16780000 }
]
四、ネスト:現実の API が取る四つの形
現実のデータは二つのコンテナの相互ネストで、パターンはほぼ四つに収束します。
| 形 | 見た目 | 典型的な場面 |
|---|---|---|
| オブジェクトが配列を持つ | {"tags": ["a","b"]} |
エンティティのリスト系フィールド |
| 配列がオブジェクトを持つ | [{"id":1},{"id":2}] |
レコード一覧、ページング結果 |
| オブジェクトがオブジェクトを持つ | {"db": {"host": "..."}} |
グループ化された設定、住所情報 |
| 配列が配列を持つ | [[1,2],[3,4]] |
行列、テーブルの行 |
典型的な API レスポンスは「外殻にオブジェクト、中身に配列」の形を取ります。
{
"code": 0,
"data": {
"items": [
{ "id": 1, "title": "first" },
{ "id": 2, "title": "second" }
],
"page": 1,
"total": 2
}
}
ネストは深さを自慢するために増やすものではありません。三、四層を超えると値へのアクセス経路が読めなくなり、消費側のコードも膨らみます。常に一緒に現れるフィールドは子オブジェクトにまとめるべきです。たとえば addrCity と addrZip を address: {city, zip} に置き換えます。
五、オブジェクトか配列か:判断表
| 問い | 答え | 理由 |
|---|---|---|
| すべての値に名前があるか | オブジェクト | キーで取得し、フィールドの追加削除が構造を壊さない |
| 同種のレコードの並びか | 配列 | 順序に意味があり、map/filter できる |
| キーで高速に引く必要があるか | キーを索引にしたオブジェクト | O(1) で直接アクセスでき、走査が不要 |
| 同じ実体の複数の属性か | オブジェクト | 属性の間に順序はない |
| 追加削除される同質の項目か | 配列 | 長さが自由に伸縮する |
一つのアンチパターンを特に挙げます。"0"、"1"、"2" といった連番キーを持つオブジェクトで配列を偽装する書き方です。これはエラーを出しませんが、配列の長さという意味と反復のための道具を失い、消費側は Object.keys を並べ替えてから値を取るという余計な手間を負います。キーが連番なら、素直に配列として書いてください。逆に、[{"key":"theme","value":"dark"}] のようなキー・値ペアのリストは、キーが動的で事前宣言できない場合を除き、オブジェクト {"theme": "dark"} のほうが優れています。
六、三大ミスとエラーメッセージの対応表
| 誤った書き方 | 典型的なエラー | 直し方 |
|---|---|---|
末尾カンマ {"a":1,} |
Unexpected token } |
最後のカンマを削除する |
シングルクォート・裸キー {name:'Ada'} |
Unexpected token ' / Expected property name |
キーも文字列もダブルクォートに統一 |
Python リテラル True/None |
Unexpected token T |
true/null に直す |
| 数値キーの偽配列 | エラーなし、意味が誤り | 本物の配列に書き直す |
位置特定のコツを二つ。パーサーが報告する位置は通常、問題の文字の後ろです。position 42 を見たら一、二文字戻って確認します。また、一行に詰められた巨大な JSON は、先にフォーマッタで改行してから調べるのがおすすめです。行と列の番号は文字オフセットよりはるかに直感的です。エラーメッセージの全文反照表はJSON エラーメッセージ逆引きに、順を追った排查の流れはJSON パースエラーの直し方にまとめてあります。
七、書き終えたら:構造を一度検証する
手書きの JSON は、納品前に必ずパーサーを通してください。最も軽い検証はコマンドラインです。
python3 -m json.tool config.json > /dev/null && echo OK
jq empty config.json && echo OK
オンラインなら、内容を JSON フォーマッタ ページに貼り付けます。構文エラーは行と列の位置付きで表示されます。ツリービューに切り替えると各階層の型がひと目で分かり、数値が文字列扱いになっていないか、配列の長さが期待どおりかを確認できます。業務側に見せるなら、配列の中にオブジェクトが入った構造は JSON to テーブル ページで行と列に展開でき、「このデータが整ったレコード一覧か」の検証も同時に済みます。
どのフィールドを配列にすべきか、深くなりすぎたネストをどう再構成するかといった構造レベルの疑問は型モデリングの話題で、続きの内容は六つの型・数値精度とエンコーディングの落とし穴にあります。
JSON の配列とオブジェクトは相互変換できますか?
できますが、対等ではありません。オブジェクトを配列に変えると、通常はキーが値に変わるためキーによる参照の利便性を失います。配列をオブジェクトに変えるには各要素にキーを与える必要があり、そのキーをどこから取るのかが新しい設計問題になります。文法的な移し替えだけを目的とせず、消費側がデータをどう読むかを先に決めてください。
オブジェクトのキーは重複できますか?
文法上は可能です。RFC 8259 は一意であるべき(SHOULD)と述べているだけです。しかし JavaScript は最後の値を採用し、C 系の一部のライブラリは最初の値を採用するなど、挙動が一致しません。署名や diff、ハッシュ計算では重複キーがそのまま結果の食い違いを生みます。生成側では重複を避け、消費側では未知の入力元からのデータを信頼できない入力として扱うべきです。
配列に異なる型の値を入れられますか?
文法上は可能で、[1, "a", true] は正当な JSON です。しかし異型の配列は、消費側のコードがすべての位置で型判定を行うことを強制し、Schema でも表現が難しくなります。行列やタプルのように位置そのものが意味を持つ場面を除き、配列は同型に保つのが賢明です。
{name:'json'} が検証を通らないのはなぜですか?
JSON ではキーと文字列値の両方にダブルクォートを要求するからです。{name:'json'} は JavaScript のオブジェクトリテラルであって JSON ではありません。{"name": "json"} に直せば検証を通ります。シングルクォート、裸キー、コメントを含む書き方は JSON5/JSONC という方言に属し、標準の JSON.parse ではなく専用のパーサーで読む必要があります。