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

公開ツールJSONスキーマ生成ツール

目次
  1. APIのレスポンスを1つ受け取っただけで、まずスキーマを手書きしたことはありませんか
  2. ツールを使わずにDraft-07スキーマを手書きする方法
  3. 生成結果を読むときに混同しやすいポイント
  4. まとめ
  5. よくある質問

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]
}
  1. 最上位の値がオブジェクトなので、最上位スキーマは"type": "object"で始まり、propertiesの中に各キーを1つずつ書いていきます。
  2. idは引用符のない数値なのでnumber、zipCodeは引用符で囲まれているのでstringです。値が引用符で囲まれているかどうかが唯一の判断基準です。
  3. addressのように値がさらに別のオブジェクトであれば、その中でも同じようにtype: objectとpropertiesを繰り返し書きます。
  4. tagsのように配列の要素がすべて同じ型なら、そのうち1つを代表としてitemsにその型だけを書きます。historyのように要素の型が混在していれば、itemsの中にanyOfを置き、出てきた型ごとにスキーマを1つずつ並べます。
  5. このデータで実際に常に存在すべきキーを人が判断してrequired配列に書きます。この判断は、例1つではなく実際のデータ全体を知っている人にしか正確にはできません。
  6. 一番上に"$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スキーマ生成ツール

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スキーマ生成ツール

JSONを貼り付けると、ブラウザ上でDraft-07スキーマがすぐに作成されます。入力したデータがサーバーへ送信されることはありません。

よくある質問

郵便番号のように数字だけで構成された値は、スキーマではどのように表示されますか?

値を引用符で囲んでいるかどうかが唯一の判断基準です。"06236" のように引用符の中に入っていれば文字列と判定され、{ "type": "string" } になります。

引用符なしで 06236 のように書くと、そもそも有効な JSON の数値ではないため(0 で始まる数値は JSON の構文エラーです)、パースの段階でエラーが表示されます。

配列の中に異なる型の値が混在している場合はどうなりますか?

配列の要素の型が複数ある場合は、型ごとに1つずつ例を取り出してそれぞれのスキーマを作り、items の中に anyOf 配列としてまとめて並べます。

たとえば配列に数値・文字列・ブーリアンが混在していると、anyOf に3つの型スキーマが並んで入ります。

「すべてのプロパティを必須に設定」チェックボックスは、具体的に何を変えるのですか?

チェックを入れると、各オブジェクトノードごとに、そのオブジェクトが持つすべてのキー名を required 配列にそのまま入れます。

一部のキーだけを選んで入れる機能ではなく、チェックを外すとどのオブジェクトにも required 配列そのものが生成されません。

生成されたスキーマ1つで実際のデータをすべて検証できますか?

生成されたスキーマは、入力欄に貼り付けた JSON の例を1つ分析した結果です。同じフィールドが実際のデータでは別の型で現れたり、例にはなかったフィールドが追加されていることもあります。

そのため、スキーマが実際のデータのあらゆるケースを自動的に保証するわけではありません。さまざまな状況をカバーするスキーマが必要なら、代表性のある例を複数それぞれ入力してみて、結果を比較する方法があります。

この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む

関連記事

  1. JSON構文エラー 原因と位置の見つけ方Unexpected tokenなどJSONのエラー位置が何を指すのか、原因になりやすい書き方とあわせて解説。メッセージを読んで原因を絞り込む手順がわかります。
  2. JSON to TypeScript変換 ?と|が付く規則JSONをTypeScriptのinterfaceにするとき、一部の要素にしかないキーに付く?(optional)や、値の型が混ざったときの|(ユニオン)がどの規則で決まるのかを実例で確かめられます。
  3. JSONをYAMLに変換するときの配列とインデントの規則JSONの配列がハイフン(-)のリストに、ネストしたオブジェクトがインデント階層になる規則と、2スペース・4スペースの違い、KubernetesやDocker Composeに貼るときの間違いを整理します。
  4. JSONPathの使い方: 記号ごとの意味を例で確認$や.属性、[数字]、[*]、..がそれぞれ何を選ぶのかを例のJSONで一つずつ確認します。フィルタ式やスライスが使えない理由も事実関係で整理しました。
  5. JWTデコード方法|構造とexp・iatの読み解き方JWTは暗号化ではなくエンコードなので、誰でも中身を読めます。header.payload.signatureの構造とbase64urlデコードの仕組み、exp・iatの秒単位の値を日時に直す方法をまとめました。
  6. JWTの署名を検証して改ざんを確認する方法JWTはheader.payload.signatureの3部分で、payloadは暗号化ではなくエンコードのみです。HMAC-SHA256の署名計算の仕組みと、検証に失敗する2つの原因(鍵の不一致・改ざん)を解説します。

関連ツール