JSON Schema生成

JSON Schemaとは

JSON Schemaは、JSONを使ってJSONデータの構造、フィールドの型、制約ルールを記述する仕様です。APIパラメータの検証、設定ファイルのチェック、データ検証、APIドキュメントでの構造説明などに利用できます。このツールは既存のJSONデータから構造を自動的に推定し、初期JSON Schemaを生成します。

JSONからSchemaを生成する方法

JSONデータを入力欄に貼り付けるか、ローカルのJSONファイルをアップロードし、Schema Draftとフィールドオプションを選択して生成します。入力データからオブジェクト、配列、文字列、数値、ブール値、nullなどのJSON型を識別し、実際のネスト構造に従って対応するSchemaを生成します。

Draft 2020-12とDraft-07の違い

Draft 2020-12とDraft-07は異なるバージョンのJSON Schema仕様です。Schemaを生成するときは、対象のバリデーター、開発フレームワーク、プロジェクトで既に使用しているSchemaのバージョンに合わせてDraftを選択してください。プロジェクトで明確な指定がない場合は、比較的新しいDraft 2020-12から始め、実行環境に応じて調整できます。

生成されたフィールドがrequiredになるのはなぜですか？

「すべてのフィールドをrequired」にするオプションを有効にすると、入力JSONオブジェクトに存在するフィールドがrequired配列に追加され、検証時に必ず存在する必要があることを示します。無効にすると、フィールドは自動的にrequiredへ追加されません。requiredが示すのはフィールドの存在であり、フィールドの値が空でないことを意味するわけではありません。

additionalPropertiesとは

additionalPropertiesは、Schemaで定義されていない追加フィールドをオブジェクトに含めることを許可するかどうかを制御します。許可する場合、入力オブジェクトには定義されていないプロパティも含められます。禁止する場合、追加プロパティはバリデーターによってSchemaに適合しないものとして扱われます。Schema生成時には、APIでフィールドをどの程度厳密に管理する必要があるかに応じて選択できます。

ネストされたオブジェクトと配列の生成方法

ネストされたオブジェクトの場合、ツールは対応するproperties構造を引き続き生成します。配列の場合は、配列要素に基づいてitems定義を生成します。配列内のオブジェクトについてもフィールドとネスト階層を分析するため、実際のJSONサンプルから比較的完全な構造Schemaをすばやく作成できます。

生成されたSchemaが初期ルールにすぎない理由

自動生成では現在のJSONサンプルから構造を推定できますが、すべてのビジネスルールを正確に判断することはできません。たとえば、現在あるフィールドが数値だからといって、将来も特定の範囲だけに限定されるとは限りません。また、現在のサンプルに存在するフィールドが、業務上常に必須とは限りません。そのためSchemaを生成した後は、実際のAPIルールに従って形式、範囲、列挙値、フィールド説明などの制約を追加することをおすすめします。

ローカルJSONファイルからSchemaを生成する方法

ファイルアップロードタブに切り替え、JSONファイルをアップロードエリアにドラッグするか、ローカルファイルを選択します。ファイルはブラウザで読み込まれて解析され、生成結果はページに直接表示されます。JSONファイルをサーバーに送信する必要はありません。生成したSchemaはコピーまたはダウンロードして、API検証やプロジェクト設定に利用できます。

生成したSchemaをどう使うか

生成したSchemaはJSONファイルとして保存し、JSON Schemaに対応するバリデーターで使用できます。実際のプロジェクトに組み込む際は、プロジェクトで使用しているDraftバージョンと、利用するバリデーターが対応しているキーワードを確認してください。特定のJSONがSchemaに適合するか確認したい場合は、JSON Schema検証ツールを使用できます。