REST APIのレスポンスを扱っていると、JSONのパースエラーや意図しないデータ構造に悩まされることは珍しくありません。エラーメッセージは往々にして「Unexpected token」や「undefined is not an object」といった手がかりの少ないものです。この記事では、JSONに関するよくある問題を素早く特定し、修正するための実践的な5つの手法を紹介します。
1. まずエラーの位置と理由を確かめる
パースエラーが出たら、最初に「どこで」「なぜ」止まったのかを確かめます。JSON.parse のエラーメッセージには位置が付くことが多く、Node.js 24 で試すと、オブジェクトの末尾カンマは「position 16 (line 1 column 17)」のように位置まで出ました。ただし同じ末尾カンマでも配列の中にあると「Unexpected token ']'」としか出ず、位置が分かりません。また、APIのレスポンスのように1行に圧縮されたJSONでは、位置が「1行目の1万8千文字目」と分かっても、その場所を目で探すのは困難です。JSON Studio に貼り付けると、何行目の何列目で止まったか、理由（末尾の余分なカンマ、シングルクォート、カンマの付け忘れ、文字列の中の生の改行など）、そしてその前後の文字列がエラー位置に印を付けた形で表示されます。配列の末尾カンマのように JSON.parse が位置を出さない場合でも、文法どおりに読み直して位置を出します。
この手順で使うツール
JSON Studio
JSON フォーマッター & バリデーター
2. 構文を直したら、整形して中身の型を見る
整形（フォーマット）は、構文として正しいJSONにしか使えません。末尾カンマやシングルクォートが残っていると整形そのものができないので、先に1の手順で構文を直します。構文が通ったら、インデントを付けて整形し、構造と型を確かめます。構文は正しいのに動かない、という問題の多くはここで見つかります。たとえば数値がダブルクォートで囲まれて文字列になっている（"price": "1200"）、あるはずのキーが無いのか値が null なのかの取り違え、配列のはずが1件のときだけオブジェクトで返ってくる、といったものです。これらはJSONとしては正しいので、パースエラーにはなりません。整形すると入れ子の深さがインデントで見えるため、括弧の対応を目で追う必要もなくなります。
この手順で使うツール
JSON Studio
JSON フォーマッター & バリデーター
3. JSONスキーマバリデーターで型を検証する
2で見つけたような型の取り違えを、毎回目で確かめるのは大変です。データが「正しい型・形式」かどうかを機械的に確かめたい場合はJSONスキーマを使います。JSONスキーマはデータ構造の設計図で、`"type": "string"` や `"minLength": 1`、`"format": "email"`、`"type": "integer"` といったルールを定義できます。JSON Schema Validator にスキーマとデータを入力すると、どのフィールドがどのルールに違反しているかを一覧で出します。注意したいのは、バリデーターによって対応しているキーワードが違う点です。このツールは `$ref` や `oneOf` のように検査していないキーワードがスキーマに含まれていると、その一覧を警告として出します。警告が出ているときの「Valid」は、その条件まで確かめた結果ではありません。OpenAPI のスキーマ定義を流用する場合、OpenAPI 3.1 はJSONスキーマと揃っていますが、3.0 には nullable のような独自の書き方があるので、そのままでは通らないことがあります。
この手順で使うツール
JSON Schema Validator
JSON と JSON Schema を並べてリアルタイムバリデーション
4. JSON Diff で変更前後を比較する
APIのレスポンス形式がバージョンアップで変わった、または環境によって返り値が微妙に異なるという状況では、2つのJSONを並べて差分を確認します。JSON Diff は、キーの追加・削除・値の変化を色付きで表示し、変わった場所を items[1].name のようなパスで示します。テキストとして比べるのと違い、オブジェクトのキーの順序が違うだけなら差分として出しません。配列は位置ごとに中まで比べるので、10件のうち1件の1項目だけが変わった場合も、その1項目だけが出ます。一方で、配列は位置で比べるため、先頭に1件追加されると、後ろの要素がすべて1つずつずれて「変更」として出ます。並び順に意味のない配列を比べるときは、先に同じキーで並べ替えてから比べてください。本番とステージングの差異を調べるときにも使えます。
この手順で使うツール
JSON Diff
2つのJSONを比較して追加・削除・変更をカラーハイライトで表示
5. JSON Pathでネストを素早くナビゲートする
ネストが深いJSONから特定のフィールドを取り出す場合、手動でオブジェクトを辿るのは非効率です。JSON Pathはパスの記法でフィールドを指定でき、`$.store.books[?(@.price < 10)].title` のようにフィルタ条件も組み込めます。JSON Path Tester にデータと式を入力すると、条件に一致する値がすべて抽出されます。この式で価格が10未満の本の題名だけが取り出せることは、実際にテスターで確かめています。コードで使う場合、Node.js の jsonpath ライブラリなど各言語に実装がありますが、JSON Path は長く実装ごとに方言があり、2024年にようやく RFC 9535 として標準化されたばかりです。フィルタの書き方や `..` の扱いが実装によって違うことがあるので、テスターで確かめた式は、使うライブラリでも一度動かしてから組み込んでください。
この手順で使うツール
JSON Path Tester
JSONPath 式をリアルタイムでテスト・結果を即確認
まとめ
JSONのデバッグは「エラーの位置と理由を確かめる → 構文を直して整形し型を見る → スキーマで機械的に検証する → 変更前後を差分で比べる → 必要な値をパスで取り出す」の順に進めると、当て推量なしで原因にたどり着けます。特に「整形は構文が正しいJSONにしか使えない」「バリデーターが検査しないキーワードがあると Valid は保証にならない」「配列の差分は位置で比べるので、先頭への追加は全件の変更に見える」の3点は、知らないと調査の方向を誤ります。