JSON Schema が実際に解くもの
要点：Schema は構造と型を統制し、業務上の意味は統制しません。フィールド欠落、型違い、範囲外の enum を止め、金額がゼロ超といった規則はコードに残ります。
要点：JSON Schema に構造、型、範囲、形式を強制させ、フィールドをまたぐ規則、業務不変条件、外部状態はコードに残しましょう。公開 API や共有ペイロードには採用し、五つのフィールドの内部サービスには不要です。
「このデータの形は正しいか」に答えます。「このデータは意味が通るか」には答えません。
得意なこと
構造の完全性。 どのフィールドが存在しなければならないか、追加が許されるか（required、additionalProperties）。
型。 port が数値か文字列か、tags が配列かスカラーか。これだけで多言語システムの防御コードが大幅に減ります。
範囲。 enum、minimum/maximum、文字列と配列の長さ。
形式。 日付、メール、URI、UUID の format。それを強制するバリデータとともに。
ネスト。 オブジェクトと配列の各階層が独自の制約を持ち、エラーが正確なパスを運びます。
ドキュメント。 Schema が契約です。フィールドを変えれば差分が影響範囲を示します。型やフォームも生成するので、一つの定義が複数の消費者を養います。
できないこと
フィールドをまたぐ依存。 「終了は開始より後」は if/then/else で表現できますが、結果は数行のコードより長く読みにくくなります。
業務不変条件。 「在庫は負にならない」は外部状態に依存します。Schema は一文書しか見ません。
意味論。 price: -100 は {"type": "number"} を完全に満たします。それが正当な価格かは Schema の知識の外です。
実行可能な分担
| 層 | 担当 |
|---|---|
| 構文：正しい JSON か | パーサー |
| 構造：フィールド、型、範囲、形式 | JSON Schema |
| 意味論：フィールド間、業務規則、外部状態 | アプリケーションコード |
| 安全性：サイズ、深さ、レート | ゲートウェイ / ミドルウェア |
これらを一か所に押し込むと、Schema は数百行、if/then 五階層に育ちます。その時点で人々はそれを迂回します。
割に合う場面
- 消費者が不明な公開 API
- 同じペイロードを読む複数サービス
- 綴り間違いを早く失敗させたい設定駆動システム
- 契約から型やフォームを生成する場合
五つのフィールドと一つのフロントエンドを持つ小さな内部サービスでは、手書きのチェックの方が保守が速いです。そこに Schema を持ち込むのはマイナスの仕事です。
FAQ
JSON Schema を採用すべきかはどう決めますか？
公開の消費者、同じペイロードを読む複数サービス、型やフォームを生成する必要性を秤にかけます。五つのフィールドと一つのフロントエンドを持つ小さな内部サービスでは、手書きのチェックの方が保守が速いです。
フィールドをまたぐ規則をコードに残すべきなのはなぜですか？
「終了は開始より後」は if/then/else に押し込めますが、結果は数行のコードより長く読みにくくなります。Schema は外部状態も見られません。
Schema はペイロードのサイズとネストの深さを検証すべきですか？
いいえ。Schema は構造を記述し、サイズや深さは記述しません。それらの制限はゲートウェイやミドルウェア層に属します。