API設計

JSON Schema じぇいそんすきーま

JSONバリデーションスキーマ定義REST APIOpenAPIデータ型

JSON Schemaについて教えて

簡単に言うとこんな感じ！

JSON Schemaは「このデータはこういう形じゃないとダメ！」っていうルールブックだよ。たとえば「名前は文字列で必須、年齢は0以上の整数」みたいなルールを事前に定義しておくと、送られてきたデータが正しい形かどうかを自動でチェックできるんだ！

JSON Schemaとは

JSON Schemaとは、JSON（JavaScript Object Notation）形式のデータの構造・型・制約をJSONそのもので記述するための仕様です。「このフィールドは文字列でなければならない」「この項目は必須だ」「数値は1〜100の範囲内でなければならない」といったルールをJSONで書き表し、受け取ったデータが正しい形かどうかを機械的にバリデーション（検証）できます。

Web APIのリクエスト・レスポンスの形式を定義したり、設定ファイルの書き方をチェックしたり、フォームの入力内容を検証したりと、「データの形を約束ごととして定める」場面で広く使われています。プログラマー同士の認識合わせにも、ドキュメントとしても機能する、一石二鳥の仕組みです。

API開発では特に重要で、OpenAPI（旧Swagger）という人気のAPI仕様書フォーマットがJSON Schemaをベースに採用しており、「システム発注の際に受け取るAPI仕様書」はほぼJSON Schemaの記法で書かれていると言っても過言ではありません。

JSON Schemaの主なキーワード（ルールの書き方）

JSON Schemaは、以下のようなキーワードを組み合わせてルールを定義します。

キーワード	意味	例
`type`	データの型を指定	`"string"`, `"integer"`, `"boolean"` など
`required`	必須フィールドのリスト	`["name", "email"]`
`properties`	オブジェクトの各フィールド定義	名前・型・制約をネストして記述
`minimum` / `maximum`	数値の最小値・最大値	`"minimum": 0`
`minLength` / `maxLength`	文字列の長さ制限	`"maxLength": 100`
`pattern`	正規表現による文字列パターン	メールアドレス形式のチェックなど
`enum`	許可する値のリスト	`["active", "inactive", "pending"]`
`format`	特定の書式指定	`"date"`, `"email"`, `"uri"` など

具体的なスキーマ例

たとえば「ユーザー登録API」のリクエストボディのスキーマはこんな感じになります。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User",
  "type": "object",
  "required": ["name", "email", "age"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50,
      "description": "ユーザーの氏名"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "メールアドレス"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150,
      "description": "年齢"
    },
    "role": {
      "type": "string",
      "enum": ["admin", "user", "guest"],
      "description": "権限"
    }
  }
}

覚え方のコツ

「型・必須・範囲」の3点セットで考えると覚えやすいです。まずtypeでデータ型を決め、requiredで必須項目を宣言し、minimumやmaxLengthなどで値の範囲を絞る——この順番でスキーマを書いていくとスッキリ整理できます。

歴史と背景

2009年 — JSON Schemaの最初のドラフトがIETFに提出される。JSONの普及に伴いデータ検証の必要性が高まった
2013年頃 — Draft 4がリリースされ、広く実装が普及。多くのバリデーションライブラリがこのバージョンに対応
2016年 — Draft 6・7と改訂が続き、formatやキーワードの整理が進む
2019年 — Draft 2019-09（旧Draft 8）から年号ベースのバージョン管理に移行。再帰的なスキーマ定義などが強化
2020年 — Draft 2020-12がリリース。$dynamicRefの導入など柔軟性が向上。現時点での最新安定版
現在 — OpenAPI 3.1がJSON Schema 2020-12に完全準拠。Swagger UI・Postman・VS Codeなど主要ツールが標準サポート

JSON SchemaとOpenAPIの関係

JSON SchemaはAPIエコシステムのど真ん中に位置しています。特にOpenAPIとの関係は切っても切り離せません。

JSON Schema vs その他のスキーマ定義手段

比較項目	JSON Schema	Protocol Buffers	XML Schema (XSD)
記述形式	JSON	独自DSL（.proto）	XML
主な用途	REST API・設定ファイル	gRPC・内部通信	SOAP・行政系システム
人間の読みやすさ	◎ 高い	△ 要学習	△ 冗長になりがち
バイナリ効率	△ なし	◎ 高効率	△ なし
ツールサポート	◎ 豊富	○ 充実	○ レガシー系に多い
OpenAPIとの親和性	◎ 標準採用	△ 別途変換必要	✕ 非対応

規格・RFC番号	内容
RFC 8259	JSON（JavaScript Object Notation）の基本仕様
RFC 6901	JSON Pointer（JSON Schema内で`$ref`参照パスに使われる）
RFC 6902	JSON Patch（JSONデータの差分操作。スキーマと合わせて使われる）