実践的な API 検証のための JSON Schema

JSON Schema は、API が実際に依存している payload の形を説明するときに特に役立ちます。すべての業務ルールを表現しなくても、欠けたフィールド、型の違い、予期しない enum、チーム間の契約ズレを検出できます。

API デバッグでは「見た目では正しそう」な JSON がよくあります。Schema を使うと、その感覚的な確認を再現可能な検証へ変えられます。

契約の境界から始める

良い schema は境界を対象にします。

• 外部 API から受け取るレスポンス
• フロントエンドから送る request body
• webhook payload
• キューに積む message
• テスト fixture

内部のすべてのオブジェクトを schema 化する必要はありません。まず壊れると困る入出力の境界に絞ると、効果が出やすくなります。

最初は小さくてよい

実務では、最初から完全な schema を書こうとすると止まりがちです。まず必須フィールド、基本型、配列かオブジェクトか、主要 enum だけを定義しても価値があります。

{
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string" }
  }
}

この程度でも、id が文字列になった、email が欠けた、payload 全体が配列になった、といった問題を早く見つけられます。

デバッグでの使い方

まず実際の JSON を整形します。次にサンプルから schema を作るか、既存 schema と照合します。エラーが出たら、schema が厳しすぎるのか、payload が契約から外れているのかを確認します。

JSON Schema はレビューの代わりではありませんが、API 契約を人間の目だけに頼らない形へ近づけます。