01
外側の配列が何を表すか選ぶ
単一文書では外側の配列も実データで、出力のルートはarrayになります。複数サンプルでは各要素を独立した文書として統合します。配列文書を複数比較する場合は配列をさらに配列で囲みます。
サンプルから設計へ
JSON Schema生成観測した値を契約のたたき台に
まず例を試してください。外側の配列を独立した文書の集まりとして使う場合だけ、複数サンプルを選びます。
JSON Schema生成
JSONサンプル
スキーマ出力
処理はこのブラウザー内で行い、サンプルを送信・保存しません。
1件のサンプル・7項目・0件の列挙・0件を省略
JSON Schema生成は、正式な仕様がなく、APIの応答例だけが手元にあるときに役立ちます。成功した一件だけでは消える項目や型の揺れを見つけられないため、代表的な記録を組み合わせて確認します。
プロパティの欠落とnull値は別の状態です。必須プロパティでもnullを許可でき、nullを許可しない項目でも省略可能にできます。画面では存在条件と値の型を分けて指定します。
JSON Schema生成で違いを確認
先頭の記録だけで決めない
JSON Schema生成は同じ構造位置の配列要素をすべて調べます。一件にしかないキーは共通の必須項目から外れ、明示的なnullは型に残ります。別の場所にある同名キーまで一つにまとめることはありません。
手で追加した制約を守る
編集を開始すると自動生成が止まります。説明や業務条件を書き足した後に再生成しても、現在の内容は候補で上書きされません。確認して適用すると一件のスキーマを置き換え、元に戻す操作で入力と設定も復元できます。
見落としやすい三つの選択
02
必須と可空を別々に決める
共通の必須項目は、その位置のすべてのオブジェクトにあるキーです。全項目を必須にすると、一部が欠けた元の記録を拒否する場合があります。null許可を広げてもrequiredから項目は消えません。
03
変更後の結果を更新する
入力や設定を変えた瞬間にコピーとダウンロードが無効になります。自動生成は350ミリ秒後、手動ではCtrl/Cmd+Enterで実行できます。手編後の再生成は候補の適用が必要です。
値から読み取る構造
三つのドラフトで共通の構文
JSON Schema生成ではDraft 7、2019-09、2020-12を選べます。使用するtype、properties、required、enum、単一スキーマのitemsは共通のため、選択で変わるのは$schemaのURIです。既存スキーマの移行ではありません。
空配列は型の証拠にならない
配列のスキーマは全要素をまとめて推論します。空配列しかなければitemsは制約のない{}です。1.0や100e-2は数学的に整数なのでintegerとなり、小数が混ざればnumberになります。
列挙値は必要なときだけ
列挙値推論は初期状態で無効です。有効にすると各スカラー位置で最大20種類を集め、全位置のnull許可で加えるnullも数えます。上限を超えたenumは全体を省略し、値の一部だけを残しません。
JSONからスキーマを編集可能な形へ
大きな数も元の数値表記を保持します。1と1.0は同じ値として重複を除き、最初の表記を残します。編集後はJSONの構文とルート形状だけを確認するため、業務条件は別途検証してください。
推論に任せない判断
- 形式や範囲を推測しない
- 日時やメールのような文字列もstringのままです。format、pattern、長さ、最大最小値、既定値は推測しません。追加プロパティも許可されるため、業務仕様に合わせて制約を補います。
- 見えていない型は不明のまま
- nullだけの値から非null時の型はわかりません。空配列から要素の型も決まりません。フィールド間の相関や判別条件は保持しないため、観測していない組み合わせを許す場合があります。
- タプルや固定長を作らない
- 配列の位置に意味があるとは判断せず、全要素を同じitemsで表します。先頭要素だけの推論、参照の生成、条件分岐も行いません。必要な場合はドラフトに合った制約を手で追記してください。
- 編集済みでも意味の検証は別
- 編集結果はオブジェクトまたは真偽値を受け付け、構文エラーと重複キーは拒否します。ただしメタスキーマ、外部参照、実サンプルとの一致は検証しません。型名の誤記があっても構文検査を通ることがあります。
- 文書全体に上限がある
- 入出力は各500,000文字、50,000ノードまでです。入力の深さは40、編集出力は100、複数サンプルは1〜1,000件です。コメント、末尾カンマ、NDJSON、ファイルやURLの取り込みは非対応で、上限超過時は全体を停止します。
JSON Schema生成のよくある質問
生成ツールはどのJSON Schemaのドラフトを使いますか?
初期値は2020-12で、Draft 7と2019-09も選べます。対象の検証器が対応するものを指定してください。このツールが出力する通常の配列構文は三つで共通です。
スキーマを生成するとき、必須プロパティはどう決まりますか?
共通設定では同じ位置の全オブジェクトにある項目を必須にします。nullでも存在していれば数えます。全項目必須、必須なしも選択できます。
emailやdateのような文字列フォーマットを推測しますか？
推測しません。値の見た目だけで業務上の形式を決めないためです。必要なformatは編集で追加し、使う検証器で扱いを確認してください。
配列のスキーマはどう推測しますか?
すべての要素を同じ位置で統合します。空配列のみならitemsは{}になります。サンプル順をタプルの位置指定として解釈することはありません。
生成したスキーマをそのまま本番で使えますか？
推論結果はたたき台です。追加項目の許可、未観測の値、フィールド間の条件などを見直し、正常例と異常例を検証してから採用してください。
推論結果で気になる点がありますか？