JSON Schema とは何か

JSON Schema は JSON データの形を記述するための語彙です。スキーマは、値がオブジェクトでなければならないこと、name フィールドが必須であること、tags が文字列の配列でなければならないこと、識別子が UUID 形式に一致すべきことなどを述べられます。

目的はドキュメントだけではありません。スキーマはバリデーター、エディター、CI チェック、API ゲートウェイ、テスト fixture で使えます。

スキーマが記述すること

最も単純な形では、スキーマは 3 つの質問に答えます。

• どの JSON 型が許可されるか？
• どのフィールドが存在してもよい、または必須か？
• 各値にどの制約が適用されるか？

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "name": { "type": "string" }
  },
  "required": ["id", "name"]
}

このスキーマは形を検証しますが、ビジネス上の真実は検証しません。id を必須にできますが、アプリケーションがデータベースでその id の存在を確認しない限り、存在を証明することはできません。

スキーマが役立つ場面

• リクエストおよびレスポンス payload
• 設定ファイル
• メッセージキューとイベントストリーム
• テスト fixture
• スクリプトや AI システムから生成されたデータ

スキーマが置き換えないもの

スキーマは JSON のパース、ドメイン検証、認可チェック、データベース制約を置き換えません。生 JSON がプログラムが信頼する値になる境界に位置します。

良いスキーマは、最良の意味で地味です。無効なデータをシステム境界の近く、本番デバッグの物語になる前に早期に失敗させます。