REST APIのレスポンスを扱っていると、JSONのパースエラーや意図しないデータ構造に悩まされることは珍しくありません。エラーメッセージは往々にして「Unexpected token」や「undefined is not an object」といった手がかりの少ないものです。この記事では、JSONに関するよくある問題を素早く特定し、修正するための実践的な5つの手法を紹介します。
1. ブラウザのコンソールで即座に検証する
最も手軽な方法は、ブラウザのデベロッパーツールのコンソールで `JSON.parse()` を直接実行することです。エラーが発生した場合、ブラウザは行番号と列番号を含む詳細なエラーメッセージを出力します。たとえば `JSON.parse('{"name": "test",}')` と入力すると、末尾カンマの位置を正確に教えてくれます。APIから受け取ったレスポンスをそのままコピーして貼り付けるだけで、データの問題を素早く切り分けられます。また、コンソールではパースしたオブジェクトをインタラクティブに展開できるため、ネストが深い構造でも目的のフィールドを素早く見つけられます。
2. JSONフォーマッターでインデントを統一する
ミニファイ（圧縮）されたJSONは、エラー箇所を目視で確認することがほぼ不可能です。JSON フォーマッターを使ってインデントを整形すると、構造のズレや閉じ括弧の位置ミスが一目でわかるようになります。特に注目すべきポイントは、配列の末尾に不要なカンマがないか、文字列のクォートがシングルではなくダブルになっているか、数値がクォートで囲まれていないか（意図せず文字列になっていないか）の3点です。整形後のJSONをエディタの括弧マッチング機能と組み合わせると、対応する括弧がすぐに見つかり、ネストのズレを素早く特定できます。
3. JSONスキーマバリデーターで型を検証する
データが「存在する」かどうかだけでなく、「正しい型・フォーマット」かどうかを検証したい場合はJSONスキーマを使います。JSONスキーマはデータ構造の設計図で、`type: "string"` や `minLength: 1`、`format: "email"` といったルールを定義できます。バリデーターにJSONスキーマとデータを入力すると、どのフィールドがどのルールに違反しているかをリスト形式で出力します。フロントエンドとバックエンドの境界でデータ形式の認識齟齬が起きている場合、スキーマを共有の「契約」として扱うことでミスを事前に防げます。APIのドキュメントとしてスキーマを公開している場合は、OpenAPI Spec（旧Swagger）のスキーマ定義をそのまま流用することも可能です。
4. JSON Diff で変更前後を比較する
APIのレスポンス形式がバージョンアップで変わった、または環境によって返り値が微妙に異なるという状況では、2つのJSONを並べて差分を確認することが重要です。JSON Diffツールは、キーの追加・削除・型変更・値の変化を色付きでハイライト表示します。単純なテキスト比較と違い、フィールドの順序が変わっても意味上の差分のみを検出できるため、本質的な変更箇所を見落とさずに済みます。特に本番とステージングの環境差異を調べる場合や、外部APIのレスポンスが時刻によって変化する場合に重宝します。差分を確認した後は、変更されたフィールドに絞って単体テストを書く習慣をつけると、同じ問題の再発を防げます。
5. JSON Pathでネストを素早くナビゲートする
ネストが5層以上あるJSONから特定のフィールドを取り出す場合、手動でオブジェクトを辿るのは非効率です。JSON Pathはファイルシステムのパス記法に似た記述でフィールドを指定でき、`$.store.books[?(@.price < 10)].title` のようにフィルタリング条件も組み込めます。JSON Pathテスターにデータと式を入力すると、条件に一致するすべての値を即座に抽出します。コード上でも、Node.jsであれば `jsonpath` ライブラリ、PythonやGoにも同等のライブラリが存在するため、テスターで確認した式をそのままコードに移植できます。複雑なAPIレスポンスの特定フィールドだけをモニタリングする場合にも活用できます。
まとめ
JSONのデバッグは、適切なツールを使えば大幅に短縮できます。コンソール検証・フォーマット整形・スキーマバリデーション・Diff比較・JSON Pathという5つのアプローチを状況に応じて使い分けることで、「なぜこのエラーが出ているのか」にかける時間を最小化できます。特にスキーマバリデーションは事前にエラーを防ぐ投資として有効で、長期的なコードの安定性に大きく貢献します。