プロジェクトがJSONスキーマを必要とする正確な瞬間を知るのに十分なAPIを出荷しました それは決して開始時ではありません 3 週間後、セカンドチームがエンドポイントを消費し始め、誰かが不正なリクエストボディを送信し、 null 誰もが常に文字列だと思っていたフィールドにスリップします。突然、契約書が必要になります。機械が強制できる形式で " 有効なペイロードは次のようになります。 "その文書は JSON スキーマであり、すでに実際のデータを返すエンドポイントから手で 1 つ書き込むことは、バックエンド作業における最も退屈な仕事の 1 つです。
tl;dr: JSON サンプルを に貼り付けます JSON スキーマジェネレーター、ドラフト-07 または2020-12 をピックし、スキーマ - 型を推測します、
requiredフィールド、マージされた配列項目、および文字列形式date-timeあんどuuid。ブラウザで完全に実行されるため、トークンと個人データを運ぶペイロードはページから離れることはありません。出力を強力な初稿として扱い、次に自分だけが知っている制約で締め付けます。
私がこのツールを Toolz.dev 用に構築したのは、同じことを手作業でやり続けたからです: レスポンスボディを開き、目を細めて、その形状をスキーマ節ごとに書き起こすのは反復的であり、反復的な書き起こしは間違いが隠れる場所です。このガイドでは、ジェネレーターが何をするか、推論が信頼できる場所、判断が必要な場所、生成されたスキーマが実際の検証ワークフローにどのように適合するかを説明します。
JSON スキーマとは何ですか?なぜデータから JSON スキーマを生成するのでしょうか?
JSON スキーマは、JSON の構造を記述するための語彙であり、次のように維持されます それ自体が仕様です 慣習としてではなく. スキーマ自体は, 各フィールドの期待型, どのフィールドが必要か, ネストされたオブジェクトや配列がどのような形状をとるか, および - のようなキーワードを宣言する JSON ドキュメントである pattern、 enum、 minimum、そして format - 実際に許可される値とは ほぼすべての言語のバリデータがスキーマを読み取り、特定のドキュメントが準拠しているかどうかを教えてくれます。これは、JSON の世界がサービスの境界を越えて移動する型システムに最も近いものです。
サンプルからスキーマを生成する理由は、それを最初から書くのではなく、スキーマのほとんどが機械的なものであるためです。 payload を歩いて " を記録するこれは文字列、これは整数、このオブジェクトにはこれらのキーがあります " はまさにマシンが行うべき種類の作業です でないよ 機械的なのは意味層です。それを知ること status 4 つの文字列のうちの 1 つだけである可能性があります age 否定的になることはできません、それは email 実際のアドレスパターンに一致する必要があります.generation は機械的な足場を処理するため,重要な制約に注意を費やすことができます.空白のファイルから始めてすべてのフィールドを覚えていることを期待するのではなく,すでに現実に一致するドキュメントから始めてルールを追加します.
信頼の次元もあります スキーマを手で入力すると 何をエンコードするかです 信じろ エンドポイントが返します 信念は現実から漂います - フィールドが追加され、整数はnullableになり、単一のオブジェクトを返したエンドポイントは配列を返し始めます 実際の応答から生成されたスキーマは、サービスがキャプチャした日に真に送信したものに固定されます そのアンカーは、ステージングで検証が合格し、本番環境で失敗する理由をデバッグしているときに非常に価値があります。
ジェネレータがスキーマをどのように推測するか
エンジンは JSON を解析し、値を再帰的にウォークして、構造のあらゆる部分に対してスキーマ ノードを放射します。緩すぎるスキーマは役に立たず、厳密すぎるスキーマは有効なデータを拒否するため、ルールは意図的に保守的です。
スカラーの場合は区別されます integer から number ー 42 なる integer、 4.2 なる number ー なぜなら、その区別はバリデーターにとっても、スキーマを読んでいる人にとっても意味があるからです。 ブール値と null 独自の型に写像します 文字列は になります type: string、そしてフォーマット検出がオンの場合、エンジンはよく知られたパターンのセットに対して値を確認し、それにタグを付けます: date-time、 date、 time、 email、 uri、 uuid、そして ipv4。
オブジェクトの場合、すべてのキーを記録し、各値のスキーマを推測し、-if を推測します required 推論は有効です - その位置のすべてのオブジェクトに存在する場合に必要なキーをマークします。すべてのキーを意味する単一のオブジェクトの場合; 興味深いケースは配列です。
オブジェクトの配列の場合 ジェネレータは単純なウォークよりも 便利なことを行います 各要素やスプロール化に対して 別々のスキーマを発するのではなく anyOf ほぼ同一の形状で、配列内のすべてのオブジェクトを 1 つに結合します items 単一の要素を記述するスキーマ.すべての要素に存在するキーは必須です; 一部の要素のみに存在するキーはオプションのままです.これは実際の API コレクションの動作を反映します: ほとんどのレコードが an を運ぶページ分割されたリストです avatarUrl しかし、いくつかはそうではありません。 merged スキーマは " をキャプチャしますこれらのフィールドは常に表示され、これらは時々表示されます" 1 つの読み取り可能な定義で これは組み込みサンプルで見ることができます members 配列には 2 つのオブジェクトがあります。1 つは an を持っています active フィールドと - を含まないフィールド、および生成されたアイテム スキーマ マーク id あんど role 必須ですが、残ります active オプション.
混合スカラーの配列の場合、エンジンは要素タイプを 1 つに折りたたみます type 配列 - ["integer", "string", "boolean"] ー 冗長な結合ではなく。 object と non-object の図形が 1 つの配列に真に混ざり合うと、 にフォールバックする anyOf、これは " の正しい JSON スキーマ構造です これらの代替の 1 つです。"
JSON スキーマジェネレータの使い方
ステップ1:代表的なサンプルを貼り付けます
API レスポンス、フィクスチャ、コンフィグファイル、または Webhook 本体をドロップインします。 精度を得るためにできる最も重要なことは、 を貼り付けることです 代表 サンプル. real response からいくつかのレコードがある場合は,それらをすべて配列の中に含める - ジェネレータはそれらをマージし,オプション性を正しく推論する.1 レコードのサンプルは,エンジンが見るすべてのフィールドが常に存在することを指示するが,これはしばしば間違っている.組み込みサンプルを最初にロードして,入れ子になったオブジェクト,オブジェクトの配列,フォーマットされた文字列が,どのように扱われるかを確認してから,自分のものを貼り付ける.
ステップ2:方言を選ぶ
検証ライブラリー間で最も広い互換性のために Draft-07 をピックアップするか、現在の仕様のために 2020-12 ツールが正しいものを書き込みます $schema identifier on the root so your validator applies the right rules.このジェネレータが生成するオブジェクトと配列の形状に対して、構造出力は両方の方言で同じです; 目に見える違いは識別子です。 draft-07 は、ツーリングがサポートする内容が不明な場合は、安全なデフォルトです - どのバージョンよりも幅広いライブラリ サポートがあります。
ステップ3:オプションを設定します
を追加します title スキーマをセルフドキュメント化したい場合。 emitするかどうかを決定します required ーほとんどの場合、それを望みますが、初期の探索では、より緩やかなスキーマが好まれるかもしれません。 false positives が表示されていない限り、フォーマットの検出はオンにしておいてください。 and turn on strict mode (厳密モードをオンにします)additionalProperties: false) スキーマが、構成ファイルやリクエスト本文など、完全に制御できるものを保護しており、予期しないキーを無視するのではなく拒否したい場合。
ステップ4:生成、レビュー、エクスポート
Generate を押してから、出力を批判的に読みます。 をチェックします required は意図と一致し、整数対数値は正しく出てきて、検出されたフォーマットはすべて偶然ではなく正しい。正しく見えるときは、スキーマをコピーするか、スキーマを としてダウンロードします .json ファイルをバリデータまたはリポジトリにドロップする準備が整いました。
実用的な例
仮説からのこの応答を考えてみましょう /projects エンドポイント:
{
"id": "5b2a1f6e-8c3d-4a1b-9f7e-2c1d3e4f5a6b",
"name": "Toolz",
"createdAt": "2026-01-14T09:30:00Z",
"score": 4.8,
"members": [
{ "id": 1, "role": "owner", "active": true },
{ "id": 2, "role": "editor" }
]
}
ジェネレータは、スキーマを生成します id を持つ文字列です format: "uuid"、 createdAt を持つ文字列です format: "date-time"、 score は a number (小数のため整数ではありません)、および members が配列である items スキーマが必要です id あんど role でもない active. 最後の詳細は見返りです。2 人のメンバーの例から、それが正しく推測されました active はオプションです。大きなペイロード上でその推論を手作業で行うことは、まさにジェネレーターが削除する、慎重で退屈な作業です。
推論が終わり、あなたの判断が始まる場所
限界について直接的に説明したいと思います。なぜなら、生成されたスキーマが本番環境に直接渡されるのは間違いだからです。推論には型と構造が見えます。インテントが見えません。
それは知ることができない role は の 列挙型 owner、 editor、そして viewer ーサンプルからは、それしか知らない role は文字列です. それは知り得ません. score 0から5までの範囲です name は最大長を持つ、あるいは、たまたまUUIDのように見えるコードは、実際には、プレーンな文字列のままであるべき不透明な識別子であることを、UUIDは、UUIDは、UUIDは、UUIDは、UUIDは、UUIDは、UUIDは、UUIDは、UUIDは、UUIDは、UUIDは、不透明な識別子であることを推測します required 存在から、従ってあなたのサンプルに偶然現れる任意分野はあなたがそれを訂正するまで要求される印を付けられる。 and it works from the data you give it: if your sample never include a null null 可能なフィールドの場合、スキーマはそのフィールドが null になり得ることを認識しません。
適切なメンタルモデルは足場ですジェネレーターはフレームを正確に構築します - あらゆるフィールド、そのタイプ、ネスティング、配列の形状、プレゼンスベースの必須リスト 次に、意味上の制約を追加します: 列挙型、パターン、数値境界、エンジンが1 つの値から見ることができなかったフォーマット これは、面倒な構造転写がすでに行われ、正しいため、何もない状態から始めるよりも速く、エラーが少なくなります。
ドラフト-07対2020-12:どちらを選ぶべきですか?
| 考慮 | Draft-07 | 2020-12年 |
|---|---|---|
| 図書館支援 | 最も広い;ほぼどこでもサポートされています | 成長中;バリデータを確認してください |
| ステータス | 広く展開、安定 | 現在の仕様 |
$schema 値 |
http://json-schema.org/draft-07/schema# |
https://json-schema.org/draft/2020-12/schema |
| 配列項目キーワード | items 単一項目スキーマの場合 |
items / prefixItems タプルのために分割 |
| ベストなとき | 最大限の互換性が重要です | 最新の仕様機能が欲しいです |
このツールが生成するスキーマについて - オブジェクト、必須リスト、単一アイテム形状の配列 - 両方の方言が同じ構造を表現します実際的な決定は、検証ライブラリがサポートするものに帰着しますスキーマを確立されたスタックに配線している場合は、検証ドキュメントのバージョンと一致します。 fresh を開始していて制約がない場合、Draft-07 は比類のないエコシステム サポートに対する実用的な選択肢のままです。
よくある使用例
既存の API のドキュメント化. スキーマのないエンドポイントを継承すると、実際の応答からエンドポイントを生成すると、数秒で正確な開始ドキュメントが得られます。その後、それをパブリッシュされたコントラクトに絞り込みます。これは、クライアント コードのタイプの生成と自然にペアリングされます。同じサンプルがフィードできます JSON から TypeScript サーバー契約とクライアント タイプが同じ真実のソースから得られるようにするためのツールです。
リクエストボディを検証します. 制御するリクエストボディの場合、有効な例からスキーマを生成し、予期しないキーを拒否するために strict モードをオンにし、エンドポイントが強制する列挙型と境界を追加します。不正なリクエストは、ハンドラーの奥深くで混乱を招く失敗を引き起こすのではなく、明確な検証エラーでエッジで失敗するようになりました。
コンフィグファイルの検証. JSON config を読み取るアプリケーションは、スキーマの恩恵を大きく受けます。 known-good config からスキーマを生成し、それを締めて起動時に検証するため、config キーの入力ミスは、機能を静かに無効にするのではなく、大声で失敗します。
テストと治具. スキーマはテストアセットを兼ねます。 CI でフィクスチャをそれに対して検証すると、形状がずれたフィクスチャが誤解を招くグリーンテストを生成する前に捕捉されます。
サービス間の契約テスト. 2 つのサービスがペイロードについて合意すると、共有スキーマが契約となります。実際のメッセージからそれを生成し、それを改良すると、両チームに独立して検証できるドキュメントが与えられます。
プライバシー: これがブラウザで実行される理由
APIサンプルは、開発者が扱うテキストの中でも最も機密性の高いものです アクセストークン、セッション識別子、電子メールアドレス、内部レコードID、そして時折、ランダムなWebフォームに決して貼り付けるべきではない個人データが日常的に含まれています JSONスキーマジェネレーターがすべての作業をクライアント側で行うのはまさにそのためです 解析、推論、シリアル化はブラウザのJavaScriptで行われます サーバーにアップロード、ログ、保存されるものは何もありません 生成中にネットワークタブを開くか、インターネットから切断することでこれを確認できます - ツールはまだ動作します ペイロードを他の人に発送するツールを使用しないので、私はこれを気にします& #39; s サーバー、そして私はあなたにどちらかを尋ねません 同じ原理が、私が長々と議論する Toolz.dev の全体を通して実行されます オンライン ツールのデータ プライバシー 書き込み.
より広範な JSON ツールキットにどのように適合するか
スキーマは、より大きな JSON ワークフローの 1 つのアーティファクトです。スキーマを生成する前に、クリーンで有効な入力 - を取得するのに役立ちます JSON フォーマッタ は、不正な形式のテキストをジェネレーターにフィードしないようにペイロードをフォーマットして検証します。 スキーマを取得した後、アプリケーション コードの型が必要になることがよくあります。 JSON から TypeScript 入ってくる。そして、パイプラインがフォーマット間を移動する場合は、 JSON から YAML へ converter は、多くの config および CI システムが期待する変換を処理します。これらの部分が でどのように接続されるかについては、私が書きました JSON ツールの究極のガイド、およびでより広範なキットを組み立てることについて Web 開発者ツールキット 概要. 接続されたツールキットのポイントは、単一のサンプルがブラウザから離れることなく、スキーマ、タイプ、形式変換などの複数のツールを介してフローできることです。
フェイク
JSON から JSON スキーマを生成するにはどうすればよいですか?
JSONをエディタに貼り付け、Draft-07 または2020-12 を選択してGenerateを押します ツールはすべてのフィールドのタイプを推測し、必要なキーを抽出し、コピーできるスキーマをバリデータに直接出力します アップロードされるものは何もありません - 推論は完全にブラウザで実行されます。
ドラフト 07 と 2020-12 の違いは何ですか?
これらは JSON スキーマ仕様の 2 つのバージョンです。 draft-07 はライブラリ間で最も広くサポートされており、安全なデフォルトです。 2020-12 は現在のリリースであり、特に配列とサブスキーマの表現方法が変更されます。オブジェクトと配列の形状の場合、このツールは構造を生成します。同じ; 主な目に見える違いは、 $schema 識別子.
必要なフィールドをツールはどのように決定しますか?
キーは、ジェネレーターが見るすべてのオブジェクトに表示されるときに必須とマークされます。 すべてのキーを意味する単一のオブジェクトの場合、オブジェクトの配列の場合、すべての要素に存在するキーを意味します。 一部のレコードのみに表示されるキーは必須ではありません。API がオプションのフィールドを省略する方法を反映しています。 必要なフィールド検出を完全にオフにすることができます。
オブジェクトの配列はどうなりますか?
オブジェクトは 1 つに統合されます items 単一の要素を記述するスキーマ、およびプロパティはその配列として型付けされます。 eury 要素に存在するキーは必須になります; 一部のみに存在するキーはオプションのままです。これにより、大きなを生成するのではなく、スキーマを読みやすく保ちます anyOf ほぼ同一の形状の.
どの文字列形式が検出されますか?
それは認識します date-time、 date、 time、 email、 uri、 uuid、そして ipv4 文字列を作成し、一致するものを追加します format キーワード. detection is best-effort from the single sample, so review the results - a code that look at happens to be tagged as one.キーワード.検出は単一のサンプルからベストエフォートされるので、結果を確認します.plain string typesを好む場合、フォーマット検出を無効にすることができます。
単一のサンプルからスキーマを生成できますか?
はい、しかし、1 つのサンプルでは可能な形状が 1 つだけ表示されます。サンプル内の数値であるフィールドは、他の場所では null または文字列である可能性があり、たまたま存在するオプションのフィールドには必須のマークが付けられます。サンプルが代表的であるほど、理想的には複数の実際のレコードであるほど、推論されたタイプと必要なリストはより正確になります。
生成されたスキーマは本番環境の検証の準備ができていますか?
完成した文書ではなく、強力な出発点として扱う。 inference は型、構造、必須フィールドを正確にキャプチャしますが、意味上の制約 - 列挙型、文字列パターン、数値の最小値と最大値、1 つの値からは見えない形式 - は、まだ手で追加する必要があります生成すると、それらのルールに集中できるように、面倒な足場が削除されます。
私の JSON はサーバーにアップロードされていますか?
いいえ 推論エンジン全体がブラウザのJavaScriptとして実行されます 何も送信、ログ、保存されません 生成中にネットワークタブを見ること、またはインターネットから切断することによってこれを確認できます - ツールはまだ機能します。
