JSON Schema 実践例：オブジェクト、配列、列挙型、条件分岐

JSON Schema は JSON データの構造と制約を記述します。API 契約、設定ファイル、インポート処理のルールを機械的に検証できる形にするために使えます。

オブジェクトと必須項目

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "status"],
  "properties": {
    "id": { "type": "string", "minLength": 1 },
    "status": { "enum": ["pending", "active", "disabled"] }
  },
  "additionalProperties": false
}

additionalProperties: false は誤字や予期しないキーの検出に便利です。ただし、将来フィールドが増える公開 API では互換性を考えて使用してください。

ネストしたオブジェクト

{
  "type": "object",
  "required": ["name", "address"],
  "properties": {
    "name": { "type": "string" },
    "address": {
      "type": "object",
      "required": ["country", "postalCode"],
      "properties": {
        "country": { "type": "string", "minLength": 2 },
        "postalCode": { "type": "string", "pattern": "^[A-Za-z0-9 -]+$" }
      },
      "additionalProperties": false
    }
  }
}

正規表現は文字列の形だけを確認します。住所が実在するか、在庫があるかといった事実はアプリケーション側で検証します。

配列と要素

{
  "type": "array",
  "minItems": 1,
  "uniqueItems": true,
  "items": {
    "type": "object",
    "required": ["sku", "quantity"],
    "properties": {
      "sku": { "type": "string", "minLength": 1 },
      "quantity": { "type": "integer", "minimum": 1 }
    }
  }
}

uniqueItems は JSON 値全体を比較します。特定フィールドだけの一意性は、通常アプリケーションやデータベースで保証します。

$defs で定義を再利用する

{
  "$defs": {
    "money": {
      "type": "object",
      "required": ["amount", "currency"],
      "properties": {
        "amount": { "type": "number", "minimum": 0 },
        "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
      }
    }
  },
  "type": "object",
  "properties": {
    "subtotal": { "$ref": "#/$defs/money" },
    "total": { "$ref": "#/$defs/money" }
  }
}

金額を正確に扱う必要がある場合は、10進文字列または最小通貨単位の整数を検討してください。

条件付き必須項目

{
  "type": "object",
  "required": ["deliveryMethod"],
  "properties": {
    "deliveryMethod": { "enum": ["pickup", "shipping"] },
    "shippingAddress": { "type": "string" },
    "pickupLocationId": { "type": "string" }
  },
  "allOf": [
    {
      "if": { "properties": { "deliveryMethod": { "const": "shipping" } } },
      "then": { "required": ["shippingAddress"] },
      "else": { "required": ["pickupLocationId"] }
    }
  ]
}

Schema は読みやすく保ちましょう。権限やワークフロー全体はアプリケーションコードの責務です。

実務での進め方

1. 正常・異常の代表サンプルを用意する。

1. JSON Schema Generatorで土台を作る。

1. 実際の契約に基づいて required と境界条件を追加する。

1. 欠落、型違い、余分なキー、空配列をテストする。

1. Schema をバージョン管理し、自動テストで実行する。

キーワードと draft の動作は JSON Schema 公式ガイドで確認できます。生成結果は出発点であり、最終的なルールは業務要件を表す必要があります。