JSON サンプルから JSON Schema を生成 — Draft 2020-12 / Draft-07

スキーマ推論が露わにするデータ設計

JSON Schema を自動生成するには、サンプル JSON を入力として与える必要があります。このサンプルには実際の API レスポンス・データベースエクスポート・フォーム入力のサンプルデータが使われることが多く、顧客のメールアドレス・ユーザー ID・権限ロール・トランザクション金額などが含まれていることがあります。

さらに、生成された JSON Schema 自体も機密情報です。additionalProperties: false のスキーマや format: "email" の付いたフィールド名は、アプリケーションのデータモデルを詳細に示します。データベーススキーマと同等の情報量を持つ JSON Schema が外部に渡ることは、システム設計書の一部を公開することと同義です。

スキーマ生成サービスにサンプルデータを送るリスク

「JSON schema generator」で検索して出るオンラインツールは、入力 JSON をサーバーで処理してスキーマを返します。サンプルデータに実際のユーザー情報が含まれていれば、それがサーバーに届きます。また、生成されたスキーマのフィールド構造から、アプリケーションのデータモデル全体が推定可能です。

開発チームが「スキーマのたたき台を作るため」に本番データのサンプルを使う場面は多いです。実際のデータを使った方がフィールドのカバレッジが正確なためですが、その判断がオンラインツールを使っている場合はデータ漏洩のリスクを生みます。

JSON.parse と局所的な型推論でブラウザ内完結

このツールは JSON.parse でサンプルをパースし、オブジェクトツリーを再帰的に走査して各フィールドの型を推論します。JSON Schema Draft 2020-12 と Draft-07 の両方の $schema 形式で出力します。format 検出 (email / uri / uuid / date / date-time / ipv4 / ipv6) は正規表現による局所的な照合で行われ、外部 API は一切呼び出しません。

入力したサンプル JSON・出力された JSON Schema のいずれもページメモリ内にのみ存在します。本番データのサンプルを貼り付けてスキーマを生成し、スキーマだけをコピーする、という作業がネットワーク送信なしに完結します。

OpenAPI 定義や AJV バリデーション設定として使う

生成されたスキーマは OpenAPI 3.1 の components/schemas にそのまま貼り付けられる形式 (Draft 2020-12) と、AJV での ajv.compile() にそのまま渡せる形式 (Draft-07) の両方を選べます。strict: true で additionalProperties: false を付けることで、未知フィールドを拒否する厳格なバリデーターを生成できます。型定義との比較が必要な場合は json-to-ts と組み合わせて、同じサンプルから TypeScript 型と JSON Schema の両方を得ることができます。サンプルを揃えてから流し込みたい場合は json-format で整形すると差分が読みやすくなります。

サンプル 1 件からの型推論アルゴリズムの限界

JSON Schema の自動生成は本質的に「目に見える 1 件のサンプルから一般化された型を推測する」操作で、推論の自由度には限界があります。本ツールは値のリテラル型から string / number / integer / boolean / array / object / null を判定し、配列の場合は要素ごとに型を求めて union として merge (例: [1, "x"] → { "type": ["integer", "string"] }) します。integer と number の区別は Number.isInteger() で行い、1.0 のような JSON リテラルがパース後に整数化されるため、サンプルが整数だけだと future の小数値を許容しないスキーマが出てしまうことがあります。

format 検出は値の文字列を正規表現で照合する局所判定です。RFC 5322 完全準拠の email バリデーションは実装が膨大になるため、format 注釈は「ヒント」として埋めるだけで実際の検証は AJV や ajv-formats に任せる設計が一般的です。enum の自動推論は現状行わず、status: "active" のような限定値もただの string として扱います (1 サンプルから「これは enum である」と判定するのは過剰推論のため)。実運用では生成後に手動で enum / minLength / pattern を追記することを想定しています。

Draft 2020-12 / Draft-07 / OpenAPI 3.0 の方言の違い

JSON Schema は IETF Draft で進化しており、本ツールが対応する Draft 2020-12 と Draft-07 では items 配列の意味が違います。Draft-07 では items: [A, B] が「タプル: 1 番目は A、2 番目は B」を意味しましたが、Draft 2020-12 ではタプル指定は prefixItems に分離され、items は「(prefixItems を超えた) 追加要素全体の型」になりました。$id / $ref の解決規則も 2020-12 で $dynamicRef が追加されるなど更新されており、古いツールチェーンとの互換性に注意が必要です。

OpenAPI 3.0 は JSON Schema Draft 04/05 ベースで nullable: true という独自フィールドを使い、exclusiveMinimum が boolean (Draft-04) だった世代に依拠しています。OpenAPI 3.1 で「JSON Schema 2020-12 完全準拠」が達成され、type: ["string", "null"] の素朴な nullable 表現が初めて公式にサポートされました。本ツールの nullable モードは 2020-12 寄りに作ってあるので、OpenAPI 3.0 に貼り付ける際は nullable: true への置換が必要です。AJV に渡すときは draft07 の方が広いバージョンの AJV (v6, v7, v8) で動作することも実務上のポイントです。