JSON整形・デバッグの実務テクニック - エラー対処法とよくある罠

API開発・データ連携の現場で必ず出会う JSON (JavaScript Object Notation)。整形されていないAPIレスポンスを目視で追うのは至難の業ですし、構文エラーの原因特定に時間を取られた経験は誰しもあるはずです。本記事では、JSON整形・デバッグの実務テクニックと、よくある罠を解説します。

JSON整形がなぜ必要か

APIから返ってくるJSONは、通常 ミニファイ (圧縮) された1行の文字列です。

{"user":{"id":123,"name":"山田太郎","email":"yamada@example.com","tags":["admin","editor"]},"meta":{"version":"1.0"}}

これでは構造が読みづらく、バグの原因も追いにくい。整形すれば一目瞭然です。

{
  "user": {
    "id": 123,
    "name": "山田太郎",
    "email": "yamada@example.com",
    "tags": [
      "admin",
      "editor"
    ]
  },
  "meta": {
    "version": "1.0"
  }
}

整形の方法5パターン

1. ブラウザの開発者ツール

Chrome / Firefox / Edge の DevTools で console.log(JSON.stringify(obj, null, 2)) と打てば整形表示。

2. オンラインツール

本サイトの JSON整形ツール のような無料サービスを使う方法。ブラウザ内処理で機密データも安全。

3. エディタ拡張

VS Code: 標準で Format Document (Shift+Alt+F) で整形。Prettier導入ですべてのJSONに自動適用。

4. コマンドライン (jq)

# jqコマンド (Mac: brew install jq)
echo '{"a":1,"b":2}' | jq .
curl https://api.example.com/users | jq '.'

パイプ経由で整形でき、フィルタ機能 (.users[].name) も強力。

5. プログラミング言語

// JavaScript
JSON.stringify(obj, null, 2);

// Python
import json
json.dumps(obj, indent=2, ensure_ascii=False)

// PHP
json_encode($arr, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

JSON構文エラーよくある10パターン

① 末尾カンマ (Trailing Comma)

// ❌ 末尾の カンマがNG
{
  "a": 1,
  "b": 2,
}

JavaScript ES2017以降では許可されますが、JSON仕様では禁止です。Pythonのdict記法に慣れていると間違えがち。

② シングルクォート

// ❌ シングルクォートはNG
{ 'name': 'yamada' }

// ✓ ダブルクォート必須
{ "name": "yamada" }

③ キーのクォート忘れ

// ❌ JavaScriptオブジェクトリテラル形式
{ name: "yamada" }

// ✓ JSON仕様
{ "name": "yamada" }

④ コメント

// ❌ JSONはコメント不可
{
  // ユーザー情報
  "name": "yamada"
}

JSON5 / JSONC など拡張仕様ではコメントが使えますが、標準JSONでは不可。VS Codeの設定ファイル等は JSONC で書かれています。

⑤ undefined / NaN / Infinity

// ❌ これらはJSONに存在しない
{ "value": undefined }
{ "value": NaN }
{ "value": Infinity }

JavaScriptで JSON.stringify すると undefined のキーは出力から消えます。

⑥ 関数 / 正規表現

// ❌ 関数も正規表現もNG
{ "callback": function() {} }
{ "pattern": /^[a-z]+$/ }

⑦ エスケープ漏れ

// ❌ 改行・ダブルクォートはエスケープが必要
{ "msg": "Hello "World"" }

// ✓
{ "msg": "Hello \"World\"" }
{ "msg": "1行目\n2行目" }

⑧ 16進数表記

// ❌ JSONは10進数のみ
{ "color": 0xFF0000 }

// ✓
{ "color": 16711680 }  // または "#FF0000" 文字列で

⑨ 数値リーディングゼロ

// ❌ 数値の先頭0は禁止 (8進数解釈防止のため)
{ "code": 0123 }

// ✓ 文字列として扱う
{ "code": "0123" }

⑩ 文字エンコード問題

JSON仕様はUTF-8が標準。BOM付きUTF-8や Shift_JIS のJSONはパースエラーの原因。

本サイトのJSON系ツール

• JSON整形ツール: 整形・ミニファイ・バリデーション。インデント幅選択可。5MB制限
• JSON構文チェッカー: 構文エラーの行・列を特定。構造ツリーも表示
• JSON配列展開: ネストした配列を表形式に展開
• CSV→JSON変換
• JSON→CSV変換
• YAML⇔JSON変換

すべてブラウザ内処理で完結。機密データを含むJSONも外部送信なしで安全に扱えます。

デバッグの実務テクニック

① エラーメッセージから行番号を読む

JavaScriptの JSON.parse は SyntaxError: Unexpected token } in JSON at position 234 のようにエラー位置を出してくれます。エディタで「234文字目」にジャンプして該当箇所を確認しましょう。

② 段階的にパース

巨大なJSONがエラーする場合、まず半分にカットしてどちらの半分でエラーが出るか確認。これを繰り返してエラー箇所を絞り込む「二分探索」が効率的。

③ オンラインバリデータの活用

本サイトのJSON構文チェッカーはエラー位置を強調表示します。コピペで即チェック可能。

④ ペアの確認

波括弧 {} や角括弧 [] の開閉ペアが合っているか確認。VS Codeなら対応する括弧がハイライト表示されます。

パフォーマンス Tips

JSON5 / JSONC / NDJSON

標準JSONの不便な点を解消した派生形式もあります。

形式	特徴	用途
JSON5	コメント / 末尾カンマ / シングルクォート許可	設定ファイル
JSONC	コメント許可 (Microsoftが提唱)	VS Code設定 (settings.json等)
NDJSON	1行1JSONオブジェクト (Newline Delimited)	ログ・ストリーミング
YAML	インデント形式・コメント可	K8s / Docker Compose / Ansible

まとめ

• JSON整形はデバッグ・コードレビューの必須スキル
• 末尾カンマ・シングルクォート・コメントは禁止
• エラー位置情報を読んで二分探索で原因特定
• 機密データを含むJSONはブラウザ内処理ツールで安全に
• 巨大JSONはサーバ側で前処理 + gzip圧縮

本サイトのJSON整形ツール および JSON構文チェッカーは完全無料、ブラウザ内処理で機密JSONも安全に扱えます。