API JSON検証チェックリスト：構文が正しい後に確認すべきこと

JSON.parse が成功しても、それはテキストがJSON構文に従っていることを示すだけです。API契約を満たしているとは限りません。レスポンスは有効なJSONであっても、必須フィールドが欠けていたり、型が違ったり、古いenumを使っていたり、金額を安全でない浮動小数にしていることがあります。

1. まずHTTP層を確認する

本文を見る前に、ステータスコード、Content-Type、文字セット、リクエストIDを記録します。JSON APIは通常 application/json または互換メディアタイプを返すべきです。204レスポンスを無理にJSONとして解析してはいけません。エラーレスポンスも、時々HTMLを返すのではなく、安定したJSON構造にする必要があります。

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-Id: req_123

プロキシやWAFがログインページを200として返すと、パーサーエラーは原因を正しく示しません。ヘッダーと本文の先頭を先に確認すると、問題を早く切り分けられます。

2. 構文とエンコーディングを検証する

レスポンスを JSON検証ツール に入れ、括弧、カンマ、引用符、エスケープを確認します。日本語、絵文字、改行、バックスラッシュ、Unicodeエスケープを含むサンプルもテストしてください。サーバーとクライアントはUTF-8で一致しているべきです。

3. ルート形状と必須フィールドを確認する

契約では、ルートがオブジェクト、配列、スカラーのどれかを明確にします。ページングAPIなら {items, page, total} のような形を約束し、データがないときだけ空配列に変わるべきではありません。各フィールドについて、欠落、明示的な null、有効値の3状態を区別します。

4. フィールド型を厳密に見る

JSONには文字列、数値、真偽値、null、オブジェクト、配列しかありません。日付、UUID、金額、識別子には追加ルールが必要です。数値が文字列で返る、配列が期待される場所で単一オブジェクトが返る、false を欠落として扱う、といった問題はよく起きます。

大きな識別子はJavaScriptの精度損失を避けるため、文字列にするのが安全です。

{
  "userId": "9007199254740993",
  "enabled": false,
  "createdAt": "2026-07-17T08:30:00Z"
}

5. JSON Schemaで契約を固定する

JSON Schemaは、必須フィールド、型、長さ、形式、enum、ネスト規則を実行可能な契約にできます。バックエンド入力検証、契約テスト、クライアント生成で再利用し、バージョン管理に入れるべきです。

まとめ

API JSON検証は、HTTP、構文、構造、型、業務ルール、互換性の順で確認します。解析成功は最初の関門にすぎません。Schema、失敗サンプル、契約テスト、一貫したエラーレスポンスがあって初めて信頼できます。