JSON Schema バリデーター

JSON Schema ツールとは？#

単独の JSON 値は、データが何であるか——ここに文字列、そこに数値——を教えます。しかし、データがどうあるべきかは教えません——age が非負の整数でなければならないか、email が必須か、tags が空を許されるか。JSON Schema は、そうしたことを語るための語彙です。あなたはスキーマ——形を記述する小さな JSON ドキュメント——を書き、バリデーターが、データのある部品がその形に合うかをフィールドごとに検査します。

このページは、1 つのスキーマエンジンで 2 つの仕事をします。検証はスキーマとデータドキュメントを受け取り、どのフィールドがどのルールに違反しているかを、それぞれの違反をドキュメント内のパスに固定して正確に教えます。推論はその逆で、サンプルの JSON 値を渡すと、構造を歩いてすべてのフィールドの型を記録することで、Draft-07 形式のスキーマをあなたの代わりに書きます。この 2 つは自然に組み合わさります——代表的なサンプルからスキーマを推論し、その後のすべてのドキュメントをそれに対して検証します。

検証は本番コードが使うのと同じ Ajv エンジンで走り、3 つのドラフト（Draft-07、2019-09、2020-12）を選択でき、strict モードのガードは緩められているため、わずかに非厳密なスキーマも拒絶されるのではなく許容されます。

使い方#

1. ツールバーの切り替えでモードを選びます:
   • 検証（既定）: 左にスキーマ、右にデータを貼り付けます。
   • 推論: 左にサンプルの JSON 値を貼り付け、右に生成されたスキーマを読みます。
2. 検証モードでは、スキーマが書かれたDraftを選びます——Draft-07 は現存するスキーマの大部分をカバーします。2019-09 や 2020-12 は、スキーマがそれらのドラフトが導入した機能を使う場合にだけ選んでください。
3. 出力のインデントを選びます——2 または 4 スペース。推論モードでは、これは生成されるスキーマの整形を制御します。
4. 右ペインはデータドキュメント（検証）か推論されたスキーマ（推論）を示します。ペインのラベルはモードに合わせて切り替わります。
5. 検証モードでは、ペインの下の違反パネルが、各違反を パス — 理由 としてリストします。ドキュメントのルートは (root) と示され、入れ子のフィールドは /age のように JSON Pointer で現れます。
6. 右ペインのコピーをクリックして推論スキーマやデータを取り出すか、サンプル / クリアで読み込みやリセットを行います。

結果は両方の入力が解析された瞬間に計算されます。スキーマやデータの構文エラーは、正確な行と列とともに、スキーマ・データ・コンパイルのどの問題かを示すタグ付きで報告されるため、どこを見るべきかが分かります。

主な特徴#

• 1 つのエンジンで 2 つのモード。 信頼できる同じバリデーターを下に敷いて、ドキュメントを検証するか、サンプルからスキーマを生成します。
• 3 つのドラフト。 Draft-07、2019-09、2020-12 はそれぞれ独自のコンパイル済みバリデーターだけを読み込むため、常にあなたが実際にターゲットとするドラフトに対して検証できます。
• 最初の 1 つだけでなくすべてのエラー。 すべての違反が収集されるため、5 つの問題を持つドキュメントは、5 往復を強いるのではなく 5 つの問題として示されます。
• パスで固定された違反。 各違反はドキュメント内の位置を指します——ドキュメント全体の問題は (root)、/user/address/zip のような正確なポインタです。
• strict モードは緩和。 未知のキーワードや最上位の型が欠けたスキーマは、コンパイル時に拒絶されるのではなく許容されて実行されます——仕事が説教ではなく検査であるツールにとって、正しい振る舞いです。
• ローカルのみ。 スキーマもデータもブラウザ内で処理されます。何もアップロードされません。

実例#

user オブジェクトは name を持たなければならず、age は非負の整数でなければならない、とします。検証モードで左に次のスキーマを貼り付けます:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

ここで両方のルールを破るドキュメント——name が欠け、age が負——をテストします:

{
  "age": -3
}

違反パネルは 2 つの違反を、それぞれ起きた場所に固定して報告します:

(root) — must have required property 'name'
/age   — must be >= 0

(root) パスは、欠けた必須プロパティがドキュメントレベルの問題であることを教え、/age は問題のフィールドをまっすぐ指します。データを {"name":"ada","age":36} に直せば、ステータスは妥当に切り替わり、違反リストは空になります。理由のテキストは Ajv 自身のキーワード表現を、本番のログと一致させるためそのまま保持しています。

よくある質問#

Draft-07、2019-09、2020-12 のどれを選ぶべきですか？#

Draft-07 が実用的な既定値です。チュートリアル、ライブラリ、OpenAPI 仕様のスキーマの圧倒的多数がそれをターゲットにしており、あなたが必要になりそうなもの（type、properties、required、minimum、format、$ref）はすべてそこで動きます。2019-09 や 2020-12 に移るのは、スキーマがそれらのドラフトが追加した機能——unevaluatedProperties や改訂された $ref の挙動など——を明示的に使うときだけです。違うドラフトを選んでもたいていは動きますが、安全な選択はスキーマの作者が意図したドラフトです。

違反メッセージが英語なのはなぜですか？#

それぞれが Ajv 自身の、各キーワードに対する理由テキスト（must have required property、must be >= 0 など）を、変更せずに受け渡したものです。ポイントは一貫性です——これらはサーバー側の検証がログに記録する文字列と正確に同じであるため、ここで一致させておけば、本番での不一致を grep するのが簡単になります。

「strict モードは緩和」とはどういう意味ですか？#

Ajv の strict モードは、不正と見なしたスキーマ——未知のキーワード、解決できない $ref、欠けた type——を拒絶します。それはビルドパイプラインでは有用ですが、仕事が渡されたスキーマに対してデータを検査することであるバリデーターツールには不適切です。このページは strict モードをオフにするため、非厳密なスキーマは例外を投げるのではなくコンパイルされて実行されます。

スキーマを推論してから、それに対して検証できますか？#

はい——それが意図された往復変換です。推論モードで代表的なサンプルを貼り付け、生成されたスキーマをコピーし、検証に切り替えて、左にそのスキーマを貼り戻します。推論されたスキーマは元のサンプルをきれいに再検証し、以降はすべての新しいドキュメントをそれに対して検査できます。