JSONスキーマ自動作成の型判定ルールとrequired・anyOf

目次
JSONデータを貼り付けるだけでDraft-07形式のJSONスキーマがすぐに出来上がるのは、ツールが値を1つずつ再帰的に走査して型を自動判定しているからです。
APIレスポンスの例や設定ファイルを受け取って、検証ルールを急いで作らなければならない開発者、そして結果に出てくるrequiredやanyOfといったフィールドが具体的に何を意味するのか知りたい人に向けた記事です。
ここでは判定ルールと結果の読み方だけを整理し、スキーマをどう設計するのがよいかといった判断には触れません。
まとめ ① 値の型はnull → 配列 → object/string/number/booleanの順に自動判定され、引用符で囲まれた数値は必ず文字列として扱われます。 ② 配列の要素がすべて同じ型なら最初の要素1つだけを見てitemsを作り、型が混在していればanyOfで型ごとの例を並べます。 ③ 「すべてのプロパティを必須にする」にチェックを入れると、そのオブジェクトのすべてのキーがそのままrequiredに入ります。スキーマ自体は、入力した1つの例から得た推定値にすぎません。
APIのレスポンスを1つ受け取っただけで、まずスキーマを手書きしたことはありませんか
バックエンドから返ってきたJSONレスポンスの例を1つだけ手元に持っている状況を考えてみます。この例をもとに、フロントエンドの検証コードやAPIドキュメントに載せるJSONスキーマを作らなければなりません。
問題は、フィールドが10個、20個と増え始めた瞬間からです。ネストしたオブジェクトや配列、nullが混ざった値を1つずつ手で書き写していると、括弧やカンマを落としやすくなります。
とくに、配列の中に型が混在しているときにanyOfを使う文法や、どのフィールドをrequiredに入れるかの判断基準は、毎回迷いやすいところです。
ツールを使わずにDraft-07スキーマを手書きする方法
Draft-07のJSONスキーマは、いくつかのキーワードの組み合わせでできています。値を1つスキーマに移すルールは次のとおりです。
- 文字列 →
{ "type": "string" } - 数値(整数・小数の区別なし) →
{ "type": "number" } - 真/偽 →
{ "type": "boolean" } - null →
{ "type": "null" } - オブジェクト →
{ "type": "object", "properties": { ... } } - 配列 →
{ "type": "array", "items": { ... } }
サンプルのJSONにルールをそのまま当てはめてみると
このルールをサンプルのJSONにそのまま移してみます。
{
"id": 1024,
"zipCode": "06236",
"name": "山田太郎",
"isActive": true,
"note": null,
"address": { "city": "東京", "district": "港区" },
"tags": ["vip", "return"],
"history": [1, "pending", true]
}
- 最上位の値がオブジェクトなので、最上位スキーマは
"type": "object"で始まり、propertiesの中に各キーを1つずつ書いていきます。 idは引用符のない数値なのでnumber、zipCodeは引用符で囲まれているのでstringです。値が引用符で囲まれているかどうかが唯一の判断基準です。addressのように値がさらに別のオブジェクトであれば、その中でも同じようにtype: objectとpropertiesを繰り返し書きます。tagsのように配列の要素がすべて同じ型なら、そのうち1つを代表としてitemsにその型だけを書きます。historyのように要素の型が混在していれば、itemsの中にanyOfを置き、出てきた型ごとにスキーマを1つずつ並べます。- このデータで実際に常に存在すべきキーを人が判断して
required配列に書きます。この判断は、例1つではなく実際のデータ全体を知っている人にしか正確にはできません。 - 一番上に
"$schema": "http://json-schema.org/draft-07/schema#"を書き、必要ならtitleを追加して仕上げます。
このように手で書き写すと、結果は次のようになります。
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": { "type": "number" },
"zipCode": { "type": "string" },
"name": { "type": "string" },
"isActive": { "type": "boolean" },
"note": { "type": "null" },
"address": {
"type": "object",
"properties": {
"city": { "type": "string" },
"district": { "type": "string" }
}
},
"tags": { "type": "array", "items": { "type": "string" } },
"history": {
"type": "array",
"items": {
"anyOf": [
{ "type": "number" },
{ "type": "string" },
{ "type": "boolean" }
]
}
}
}
}
フィールドが数個しかなければ、この順番をそのままたどるだけで十分です。ただしフィールドが増え、ネストが深くなるほど、同じ判定ルールを手で繰り返す作業が増えていきます。
無料のJSONスキーマ生成ツールで確認する。
JSONを貼り付けると、ブラウザ上でDraft-07スキーマがすぐに作成されます。入力したデータがサーバーへ送信されることはありません。

生成結果を読むときに混同しやすいポイント
生成されたスキーマを目で確認するときに、よく誤解が生じるポイントをまとめました。
| よくある誤解 | 実際の動作 |
|---|---|
| 「"06236"のように数字だけの値もnumberと判定される | 引用符で囲まれていれば必ずstring型です |
| 整数はinteger、小数はnumberと区別される | typeof基準なので、整数・小数の区別なく常にnumberです |
| requiredチェックは必要なフィールドだけを選んで入れてくれる | チェックすると、そのオブジェクトのすべてのキーが例外なくrequiredに入ります |
| 配列の要素が複数あれば、すべて調べてまとめて作られる | 型が同じなら最初の要素1つだけを見てitemsを作ります |
| 生成されたスキーマは取り得るすべてのデータ形状を保証する | 入力した1つの例だけから推論した結果にすぎません |
配列の要素がオブジェクトのとき、いくつかの例外
配列の要素がすべてオブジェクトのときは、このルールがとくにはっきりと現れます。要素がすべて"object"型で同じだと判断されると、最初のオブジェクト1つのキー構成だけでitems.propertiesが作られます。
2つ目以降のオブジェクトにしかないキーは、スキーマにはまったく現れません。実際のデータにはあるフィールドなのに生成されたスキーマから抜けている場合は、たいていこのルールが原因です。
空の配列を入れると、itemsは制約のない{}で埋められます。要素が1つもなく、型を判定する根拠自体がないからです。
タイトル(title)の入力欄を空にしておくと、生成されたスキーマにtitleキー自体が入りません。値を入れてはじめて、$schemaのすぐ下にtitleが追加されます。
まとめ
- 値の型はnull → 配列 → object/string/number/booleanの順に自動判定され、引用符の有無が文字列と数値を分ける唯一の基準です。
- 整数と小数は区別なく、常にnumberと表示されます。
- 配列は要素の型がすべて同じなら最初の要素だけを見てitemsを作り、型が混在していればanyOfで型ごとの例を並べます。
- requiredはチェックボックスをオンにしたときだけ生成され、そのオブジェクトのすべてのキーを例外なく含みます。
- 生成されたスキーマは入力した1つの例から推論した結果なので、その例になかったフィールドや型の組み合わせまでは保証しません。
JSONを貼り付けると、ブラウザ上でDraft-07スキーマがすぐに作成されます。入力したデータがサーバーへ送信されることはありません。
よくある質問
郵便番号のように数字だけで構成された値は、スキーマではどのように表示されますか?
値を引用符で囲んでいるかどうかが唯一の判断基準です。"06236" のように引用符の中に入っていれば文字列と判定され、{ "type": "string" } になります。
引用符なしで 06236 のように書くと、そもそも有効な JSON の数値ではないため(0 で始まる数値は JSON の構文エラーです)、パースの段階でエラーが表示されます。
配列の中に異なる型の値が混在している場合はどうなりますか?
配列の要素の型が複数ある場合は、型ごとに1つずつ例を取り出してそれぞれのスキーマを作り、items の中に anyOf 配列としてまとめて並べます。
たとえば配列に数値・文字列・ブーリアンが混在していると、anyOf に3つの型スキーマが並んで入ります。
「すべてのプロパティを必須に設定」チェックボックスは、具体的に何を変えるのですか?
チェックを入れると、各オブジェクトノードごとに、そのオブジェクトが持つすべてのキー名を required 配列にそのまま入れます。
一部のキーだけを選んで入れる機能ではなく、チェックを外すとどのオブジェクトにも required 配列そのものが生成されません。
生成されたスキーマ1つで実際のデータをすべて検証できますか?
生成されたスキーマは、入力欄に貼り付けた JSON の例を1つ分析した結果です。同じフィールドが実際のデータでは別の型で現れたり、例にはなかったフィールドが追加されていることもあります。
そのため、スキーマが実際のデータのあらゆるケースを自動的に保証するわけではありません。さまざまな状況をカバーするスキーマが必要なら、代表性のある例を複数それぞれ入力してみて、結果を比較する方法があります。
この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む