はじめに
JSON はシンプルな形式ですが、書き方のルールを正確に知っておかないと、パースエラーで思わぬ時間を取られることがあります。このガイドでは、JSON で使える6つのデータ型の書き方をコード例とともに整理します。
JSON の文法は RFC 8259 と ECMA-404 で公式に定義されており、両仕様の構文は一致しています。本ガイドは同じルールを実例とともに解説し、手書きで JSON を書く際にハマりやすいポイントも合わせて整理しています。
JSON が何かという概要や、XML・CSV・YAML など他のデータ形式との違いについては JSONとは で解説しています。この記事は、その JSON を実際に手で書くときの構文リファレンスです。
文字列（String）
文字列はダブルクォート " で囲みます。シングルクォート ' は JSON では使えません。
{
"greeting": "こんにちは",
"empty": ""
}
エスケープシーケンス
文字列内で特殊な文字を使う場合はバックスラッシュでエスケープします。
| 記法 | 意味 |
|---|---|
\" |
ダブルクォート |
\\ |
バックスラッシュ |
\n |
改行 |
\t |
タブ |
\uXXXX |
Unicode コードポイント |
{
"path": "C:\\Users\\Documents",
"message": "1行目\n2行目",
"quote": "彼は\"天才\"と呼ばれた"
}
エスケープ忘れは構文エラーの原因になりやすいポイントです。特にファイルパスの \ はよく引っかかります。
数値（Number）
数値はクォートで囲まずそのまま書きます。整数、小数、負の数、指数表記が使えます。
{
"integer": 42,
"negative": -10,
"decimal": 3.14,
"exponent": 1.5e3
}
1.5e3 は 1500 を意味します。科学技術計算のデータを扱う場面で見かけることがあります。
注意点として、JSON では先頭にゼロを付けた数値（007 など）や、NaN、Infinity は使えません。これらを書くとパースエラーになります。
// これらはすべて無効
007
NaN
Infinity
（なお、JSON にコメント構文はありません。上の // は説明のために書いています。）
大きな整数の精度に注意
JSON 仕様は数値の精度範囲を定めていませんが、実装側のパーサーは大半が IEEE 754 倍精度浮動小数点を使います。これは「2^53 (= 9,007,199,254,740,992) を超える整数は精度が落ちる可能性がある」ことを意味します。
Twitter / X の snowflake ID や、Discord のスノーフレーク、その他 64bit ID を扱う API では、サーバー側が JSON 数値ではなく文字列で ID を返す慣例が定着しています。
{
"safe_id": 9007199254740991,
"snowflake_id": "9007199254740993"
}
クライアントで JSON.parse した後に BigInt 等で扱いたい場合は、文字列で受け取ってから変換するのが安全です。
真偽値（Boolean）
true と false の2値です。すべて小文字で書きます。
{
"isActive": true,
"isDeleted": false
}
True、FALSE、yes、no はいずれも JSON では真偽値として認識されません。YAML からの変換時にありがちなミスです。
null
値が存在しないことを表す null です。こちらもすべて小文字です。
{
"middleName": null,
"deletedAt": null
}
空文字列 "" と null は意味が異なります。「値はあるが中身が空」なのか「値そのものがない」のかを区別したい場面で null を使います。
配列（Array）
角括弧 [] で囲み、要素をカンマで区切ります。
{
"colors": ["red", "green", "blue"],
"scores": [85, 92, 78],
"flags": [true, false, true]
}
空の配列も有効です。
{
"items": []
}
配列には異なる型の値を混在させることも文法上は可能です。
["text", 42, true, null]
ただし、実務ではひとつの配列に入れる要素の型は統一するのが通例です。型が混在していると、受け取った側でデータの処理が複雑になります。
オブジェクト（Object）
波括弧 {} で囲み、キーと値のペアをカンマで区切ります。キーは必ずダブルクォートで囲んだ文字列です。
{
"id": 1,
"name": "商品A",
"price": 1500
}
空のオブジェクトも有効です。
{
"metadata": {}
}
キーの重複は仕様上禁止されていませんが、挙動はパーサーによって異なります。「後の値で上書き」が多数派ですが、最初の値を残すもの、エラーにするもの、両方を保持するものまであります。
{
"name": "Alice",
"name": "Bob"
}
このような JSON はライブラリによって "Alice" / "Bob" / エラーのいずれにもなりうるため、相互運用性を保つには重複キーは作らないようにします。手で書いていて気づかず重複させてしまった場合は、JSON Formatter で整形しながらキーの並びを確認してください。
ネスト構造
JSON の表現力を支えているのがネスト（入れ子）です。オブジェクトの中にオブジェクトを入れたり、配列の中にオブジェクトを入れたりできます。
オブジェクトの中にオブジェクト
{
"user": {
"name": "田中太郎",
"contact": {
"email": "tanaka@example.com",
"phone": "090-1234-5678"
}
}
}
配列の中にオブジェクト
API のレスポンスでもっとも頻繁に見かけるパターンです。
{
"users": [
{
"id": 1,
"name": "田中太郎",
"role": "admin"
},
{
"id": 2,
"name": "佐藤花子",
"role": "editor"
}
]
}
オブジェクトの中に配列
{
"order": {
"id": "A-001",
"items": [
{ "product": "ノートPC", "quantity": 1 },
{ "product": "マウス", "quantity": 2 }
],
"tags": ["urgent", "international"]
}
}
ネストが深くなりすぎると可読性が下がります。一般的には3〜4階層を超えたらデータ構造を見直すことを検討してもよいでしょう。
JSON のトップレベル
JSON のトップレベルに来られるのはオブジェクト {} または配列 [] です。RFC 8259 では文字列や数値などのプリミティブ値もトップレベルとして有効とされていますが、実務で見かけるのはほぼオブジェクトか配列です。
{
"status": "ok"
}
[1, 2, 3]
空白文字とコンパクト形式
JSON は要素間の空白文字を無視します。次の3つはすべて同じ意味になります。
コンパクト:
{"name":"田中太郎","age":30}
整形済み:
{
"name": "田中太郎",
"age": 30
}
過剰な空白:
{
"name" : "田中太郎" ,
"age" : 30
}
ネットワーク転送やストレージにはコンパクト形式のほうが容量が小さく、人が読み書きする場面ではインデント済み形式が見やすくなります。多くのライブラリやツールは出力時にどちらを使うか選べます。
よくある間違い
手書きで JSON を書くときに発生しやすいエラーを整理します。
末尾のカンマ
{
"a": 1,
"b": 2,
}
"b": 2 の後ろのカンマは無効です。JavaScript や Python のリテラルでは許容されることが多いため、これらの言語からコピペすると引っかかりがちです。
シングルクォート
{'name': '田中太郎'}
JSON ではキーも文字列値もダブルクォート必須です。シングルクォートは構文エラーになります。
キーをクォートで囲み忘れる
{name: "田中太郎"}
JavaScript では有効ですが、JSON ではキーは必ずダブルクォートで囲んだ文字列でなければなりません。
コメント
{
// これは認められない
"name": "田中太郎"
}
JSON にはコメント構文がありません。//、/* */、# のいずれも使えません。コメント付きの設定ファイルが必要な場合は JSONC や JSON5 を検討してください。詳しくは JSON にコメントは書ける？4 つの選択肢 で取り上げています。
undefined や NaN
{
"value": undefined,
"result": NaN
}
undefined も NaN も JSON では使えません。値がない場合は null を、数値計算の結果が定義不能な場合は null または文字列 "NaN" で表現します。
クォートで囲まれていない単独の文字列
hello
裸の文字列は JSON ではありません。"hello" のようにダブルクォートで囲む必要があります。
これらのエラーへの対処法は JSON Parse Errorの解決方法 で詳しく取り上げています。手書きで JSON を直しているときは JSON Formatter に貼り付けると、エラー位置を行番号付きで示してくれるので原因が一目でわかります。
クイックリファレンス
JSON で使えるすべての値の種類を表にまとめました。
| 種類 | 例 | 注意点 |
|---|---|---|
| 文字列 | "こんにちは" |
ダブルクォート必須 |
| 数値 | 42, 3.14, 1e10 |
16進数や先頭ゼロは不可 |
| 真偽値 | true, false |
小文字のみ |
| null | null |
小文字のみ |
| オブジェクト | {"key": "値"} |
キーは文字列 |
| 配列 | [1, 2, 3] |
順序付き、型混在可 |
JSON のすべての値はこの 6 種類のいずれかの組み合わせで表現できます。
整形と検証
手書きで JSON を作成したら、構文チェックを通しておくと安心です。カンマの過不足やクォートの閉じ忘れは、目視では見つけにくいものです。
JSON Formatter に貼り付ければ、整形と構文検証を同時に行えます。エラーがあればどこが問題なのかも表示されるので、修正もスムーズです。
コマンドラインで素早く確認したい場合は、次のワンライナーが定番です。
# Python 標準ライブラリ
python3 -m json.tool < file.json
# jq
jq . file.json
どちらも成功時は整形済みの JSON を、失敗時はエラー位置を表示します。Python は OS に最初から入っていることが多く、jq は色付きで読みやすい出力が得られます。
よくある構文エラーのパターンと対処法は JSON Parse Errorの解決方法 で詳しく取り上げています。JSON を見やすく整形するためのヒントは JSON整形の基本 も参考になります。API レスポンスを curl で取得して整形する方法は curl の JSON を整形する 4 つの方法 を参照してください。
データモデルが共通する YAML の書き方と比較したい場合は YAML 書き方ガイド を参照してください。インデントベースの構文との対比で JSON の特徴がより明確になります。
よくある質問
JSON にコメントは書けますか?
書けません。// も /* */ も # も JSON の文法には含まれていません。コメント付きで設定ファイルを書きたい場合は JSONC や JSON5 などの拡張仕様を使うか、"_comment": "..." のようなキーを慣習的に置く方法があります。詳しくは JSON にコメントは書ける？4 つの選択肢 を参照してください。
JSON の末尾にカンマを書いてもよいですか?
書けません。配列やオブジェクトの最後の要素のあとにカンマを置くと、ほとんどの JSON パーサーで構文エラーになります。JavaScript や Python のリテラルでは末尾カンマが許容されているため、ソースコードからコピペすると引っかかりがちなポイントです。
JSON のキーをダブルクォートで囲まないとダメですか?
ダメです。JSON のキーは必ずダブルクォートで囲んだ文字列でなければなりません。{name: "Alice"} のように裸のキー名は JavaScript オブジェクトリテラルでは有効ですが、JSON では無効です。シングルクォート 'name' も同様に使えません。
JSON のパースエラーの位置を素早く特定する方法は?
JSON Formatter に貼り付けると、エラー位置を行番号付きで表示します。コマンドラインなら python3 -m json.tool < file.json や jq . file.json でも行番号付きのエラーが得られます。よくある原因と対処は JSON Parse Errorの解決方法 で詳しく取り上げています。
まとめ
- 文字列はダブルクォート必須。シングルクォートは不可
- 数値はクォートなしで記述。先頭ゼロや
NaNは使えない - 真偽値は小文字の
true/falseのみ nullで「値がない」を明示する- 配列
[]は同じ型の要素で揃えるのが実務の慣例 - オブジェクト
{}のキーはダブルクォート付き文字列 - ネストで複雑なデータ構造を表現できるが、深すぎないよう注意
- 書き終えたら JSON Formatter で構文チェックするのがおすすめ