JSONスキーマとは|書き方の基本と自動生成の使い方

JSONスキーマ(JSON Schema)は、JSONデータが「どんな形をしているべきか」を定義するための仕組みです。APIの仕様書や、入力データのチェックに使われます。本記事では、JSONスキーマの役割と基本的な書き方を解説します。

JSONスキーマは何のためにあるのか

JSON自体には「このキーは必須」「この値は数値でなければならない」といった制約を書く仕組みがありません。そのため、受け取ったJSONが想定どおりの形式になっているかは、別途チェックする必要があります。この「あるべき形」を JSONの形式で定義したものが、JSONスキーマです。

主な用途は次のとおりです。

APIのリクエスト・レスポンスの形式を文書化する
受信したデータが仕様どおりかを自動で検証する
フォームや設定ファイルの入力補完・バリデーションに使う

基本の書き方

次のJSONを例に、スキーマの書き方を見ていきます。

// 検証したいJSON
{ "name": "太郎", "age": 20 }

// JSONスキーマ
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name", "age"]
}

typeでデータの種類(object、string、integer、arrayなど)を指定し、 propertiesで各キーの型を定義します。requiredに列挙したキーは、必ず存在しないとエラーになります。

よく使う制約の種類

キーワード	意味
type	データの型(string / number / integer / boolean / object / array / null)
required	必須のキー一覧
minimum / maximum	数値の下限・上限
minLength / maxLength	文字列の最小・最大文字数
enum	値を特定の候補の中に限定する
items	配列の各要素が満たすべき型

サンプルJSONから自動生成するときの注意点

手で書くのは手間がかかるため、サンプルのJSONから自動でスキーマを生成する方法がよく使われます。ただし、自動生成には限界があります。

サンプルに出てきたキーしか認識されません。たまにしか現れないキーがサンプルに含まれていないと、本来は使われうるキーがrequiredに含まれなかったり、逆に本来は任意のキーまで必須扱いになったりします。
数値が20だけのサンプルからは、小数を許可すべきかどうか (numberかintegerか)が判断できません。
配列の要素が1種類しかない場合、要素の型のゆらぎが考慮されません。

自動生成したスキーマは、あくまで「叩き台」として扱い、実際の仕様に合わせてrequiredや型の範囲を手で調整することをおすすめします。

スキーマで検証する前に、構文が正しいか確認する

検証対象のJSON自体に構文エラーがあると、スキーマによる検証以前の問題になります。先に JSONの構文エラーの直し方で、JSONとして正しい形式になっているかを確認してください。

まとめ

JSONスキーマは、JSONの「あるべき形」を定義し、データの検証や文書化に使う仕組みです。自動生成は手早く叩き台を作れる一方、サンプルに出てこなかったパターンは反映されないため、最終的には人の目で調整する必要があります。

サンプルからのスキーマ生成は JSON整形ツールから試せます。

戻る