JSON SchemaでAPI入力を検証する方法

このガイドで防ぐ問題

JSONの構文は正しくても、API仕様に必要な項目や型が欠けている問題を検出します。

JSON Schemaは「JSONとして読めるか」ではなく「業務・API仕様として許可する形か」を検証するために使います。構文チェックだけでは、必須項目の欠落、文字列と数値の取り違え、想定外プロパティの混入を見つけられません。

Schemaをサンプルから自動生成した場合は、それを完成仕様と考えず、required、null許可、範囲、列挙値、additionalPropertiesなどを仕様書に合わせて調整します。

WORKED EXAMPLE

ユーザー登録JSONを検証する例

idは文字列、nameは必須、ageは0以上の整数とする簡単な仕様を想定します。

{
  "id": 10001,
  "age": -1,
  "nickname": "test"
}

期待する検出
- /id: stringではなくnumber
- /name: required項目が欠落
- /age: minimum 0を下回る
- /nickname: additionalProperties=falseなら未定義項目

この例で確認するポイント

• 構文が正しいJSONでもSchemaでは複数エラーを検出できます。
• エラーパスを見て、どの項目のどの制約に違反したか確認します。
• 正常例だけでなく意図的に壊した異常例もテストします。

requiredとnull許可は別の概念

requiredはプロパティが存在するかを制約します。値としてnullを許可するかどうかはtype側で別に定義します。任意項目とnull可能項目を混同すると、クライアント実装とAPI側で解釈がずれます。

「項目が無い」「項目はあるがnull」「空文字」の3状態を仕様で区別する必要があるか確認します。

サンプル1件から制約を決めすぎない

サンプルで100が入っていたからinteger、日付らしい文字列だからdate-time、と自動決定すると別データで失敗することがあります。可能なら複数サンプルと正式仕様を参照します。

enumやmaxLengthなど厳しい制約は、実際の受入条件が確認できる場合だけ追加します。

異常系Schemaテストを用意する

Schemaそのものが正しいか確認するには、通るJSONだけでは不十分です。必須欠落、型違い、上限超過、余計な項目を意図的に作り、期待したエラーになるか確認します。

この確認を残しておくと、Schema変更時に意図せず制約を緩めたり厳しくしたりする事故を見つけやすくなります。

問題が起きる主な原因

• requiredをpropertiesだけで表現できると誤解している。
• numberとinteger、null許可を区別していない。
• 追加プロパティを許可したまま誤字を見逃している。

安全に作業する手順

1. 1

   実際の入力例からSchemaの雛形を作ります。

2. 2

   必須、型、範囲、列挙値を仕様書に合わせて修正します。

3. 3

   正常例と異常例の両方を検証します。

結果を利用する前の確認項目

• エラーパスが期待した項目を指している。
• 任意項目とnull許可を混同していない。
• 配列要素ごとの型制約が設定されている。

作業完了前のチェックリスト

• requiredとnull許可を分けて設計した
• 複数サンプルまたは仕様書を確認した
• 追加プロパティの扱いを決めた
• 正常例と異常例の両方を試した
• エラーパスが期待した項目を指すことを確認した
• 自動生成Schemaをそのまま最終仕様にしていない

この方法の限界と注意点

• サンプルから自動生成したSchemaは仕様そのものではありません。
• format検証の厳密さは実装ライブラリにより異なります。

関連する無料ツール

UtilityBoxのガイド方針

ツールの操作方法だけでなく、結果を誤用しないための具体例、確認項目、処理の限界、元データを保管すべき場面まで記載します。原因・手順・完了判定・限界を運営者が確認したガイドだけを一覧と検索対象へ掲載します。

品質確認の方法と更新方針を確認する →