JSON Schemaは、別のJSONドキュメントを使って、あるJSONドキュメントの構造がどうあるべきかを記述する方法です。コード内の条件分岐で手動でデータを検証する代わりに、期待される型、必須フィールド、値の制約を宣言的に記述し、それに基づいてデータを自動的にチェックできます。
draft-07の主なキーワード
type— 期待される値の型（object、string、number、arrayなど）。required— 必ず存在しなければならないオブジェクトのフィールドのリスト。properties— オブジェクトの各フィールドごとのスキーマの記述。enum— 値を特定の選択肢の集合に制限する。pattern— 正規表現で文字列を検証する。郵便番号の形式チェックなどに使う。
例: 日本の郵便番号のpattern
日本の郵便番号は3桁・ハイフン・4桁という固定の形式を持つ — 123-4567。配送先住所を受け取るAPIのスキーマでは、次のように書ける: "postalCode": {"type": "string", "pattern": "^\\d{3}-\\d{4}$"}。全角数字（１２３－４５６７）や、ハイフンを抜いた7桁連続の入力、〒記号付きの入力など、フォームからありがちな入力ミスをこのパターンは即座に検出できる。ただし実在する郵便番号かどうか（存在しない番号ではないか）まではこのpatternだけでは判定できず、それには別途住所データベースとの照合が必要になる。
構文検証との違い
通常のJSON検証は、テキストが構文的に正しいかどうか — 括弧、クォート、カンマが正しい位置にあるか — だけをチェックします。JSON Schemaはそれよりはるかに多くをチェックします。オブジェクトに必須フィールドemailがあるか、ageの値が文字列ではなく数値か、statusが許可された値のリストに含まれるかなどです。
なぜ必要なのか
- サードパーティAPIのレスポンスがドキュメント化された契約と一致するか確認する。
- デプロイ前に設定ファイルを検証し、早い段階でミスを見つける。
- 期待されるデータ構造を、すぐに自動チェックできる形式でドキュメント化する。
additionalProperties: 余分なフィールドを許可するかどうか
デフォルトでは、JSON Schemaは properties に記述されているもの以外のフィールドをオブジェクトに含めることを許可します — required と properties は最小限の要件を定めるだけで、網羅的な一覧ではありません。未知のフィールドを禁止したい場合は、明示的に "additionalProperties": false を追加する必要があります — このフラグがなければ、スキーマは「オープン」なままです。