JSON Schema の実例集：検証で使う定番パターン

JSON Schema を 1 分で

JSON Schema は JSON データの 許容される形とルール を記述します。構文チェックは「JSON として正しいか」、スキーマ検証は「契約どおりのデータか」を見ます。

例は Draft 2020-12（$schema）に沿っています。利用するバリデータが対応するドラフトに合わせてください。

JSON 自体の復習は JSON とは？ を参照してください。

最小の object スキーマ

スキーマ — name（文字列）と age（整数）を必須、tags は任意:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/person.min.json",
  "title": "Person",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0 },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["name", "age"]
}

有効なインスタンス

{ "name": "Asha", "age": 30, "tags": ["beta"] }

無効な例（age がなく、additionalProperties: false により extra は不可）

{ "name": "Asha", "extra": true }

文字列: 長さ・pattern・format

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "handle": { "type": "string", "pattern": "^[a-z0-9_]{3,20}$" },
    "contact": { "type": "string", "format": "email" },
    "createdAt": { "type": "string", "format": "date-time" }
  },
  "required": ["handle"]
}

メモ: format はコア仕様では注釈扱いのことが多く、Ajv などではプラグインで有効化します。ランタイムでオンにしない限り、ドキュメントとして扱うのが安全です。

数値: 境界と倍数

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "qty": { "type": "integer", "minimum": 1, "maximum": 99 },
    "price": { "type": "number", "minimum": 0, "multipleOf": 0.01 }
  },
  "required": ["qty", "price"]
}

整数には integer、小数や科学的表記には number を使い分けます。

enum と const

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "role": { "type": "string", "enum": ["admin", "editor", "viewer"] },
    "version": { "const": 1 }
  },
  "required": ["role", "version"]
}

配列: items・件数・一意性

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "ids": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[A-Z]{3}-[0-9]{4}$" },
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true
    }
  },
  "required": ["ids"]
}

anyOf / oneOf / allOf

anyOf — 少なくとも 1 つの枝が一致（「文字列 または 数値」向け）。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "value": {
      "anyOf": [
        { "type": "string", "minLength": 1 },
        { "type": "number" }
      ]
    }
  },
  "required": ["value"]
}

oneOf — ちょうど 1 枝（重なる条件に注意）。allOf — すべての部分スキーマの制約を合成。

$defs と $ref で再利用

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "Email": { "type": "string", "format": "email" }
  },
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "owner": { "$ref": "#/$defs/Email" },
    "billing": { "$ref": "#/$defs/Email" }
  },
  "required": ["owner"]
}

additionalProperties と API 契約

ルートで additionalProperties: false にすると、naem のようなタイポを検出しやすくなります。公開 API では properties と required とセットで使うのが一般的です。

よくある間違い

• • $ref のフラグメント誤りやドラフト差異で解決に失敗する。

• • null は暗黙に許可されない。許可するなら { "type": ["string", "null"] } などを使う。

• • oneOf の枝が重なると「複数一致」エラーになる。

• • integer と number の取り違え（小数は integer に合わない）。

JSON Work で試す

• • スキーマとペイロードを JSON Validator に貼り付けてブラウザ内で検証。

• • サンプル JSON から初稿スキーマを得るには JSON to Schema を利用。

本番パイプラインでは Ajv や jsonschema など、ドラフト対応を確認したライブラリ利用が一般的です。