ダイアレクトの宣言

JSONスキーマのバージョンはダイアレクトと呼ばれます。ダイアレクトは、スキーマを評価するために使用できるキーワードとセマンティクスをまとめたものです。JSONスキーマの各リリースは、JSONスキーマの新しいダイアレクトです。JSONスキーマには、スキーマが準拠するダイアレクトを宣言する方法と、独自のカスタムダイアレクトを記述する方法が用意されています。

$schema

$schemaキーワードは、スキーマがどのJSONスキーマのダイアレクトで記述されたかを宣言するために使用されます。$schemaキーワードの値は、スキーマが$schemaが識別するダイアレクトに従って有効であることを検証するために使用できるスキーマの識別子でもあります。別のスキーマを記述するスキーマは、「メタスキーマ」と呼ばれます。

$schemaはドキュメント全体に適用され、ルートレベルにある必要があります。外部参照($ref, $dynamicRef)ドキュメントには適用されません。これらのスキーマは、独自の$schemaを宣言する必要があります。

$schemaが使用されていない場合、実装では、値を外部で指定できるようにしたり、スキーマの評価に使用する必要がある仕様バージョンについて仮定を行ったりする場合があります。すべてのJSONスキーマに、リーダーやツールにどの仕様バージョンを意図しているかを伝えるために$schemaキーワードを含めることをお勧めします。したがって、ほとんどの場合、スキーマのルートにこれを配置することになります。

1"$schema": "https://json-schema.dokyumento.jp/draft/2020-12/schema"

語彙

ドラフト2019-09の新機能

ドキュメントは近日公開予定

ドラフト固有の情報

語彙の導入前は、カスタムキーワードを使用してJSONスキーマを拡張することもできましたが、プロセスはそれほど形式化されていませんでした。最初に必要なのは、カスタムキーワードを含むメタスキーマです。これを行う最良の方法は、拡張するバージョンのメタスキーマのコピーを作成し、コピーに変更を加えることです。カスタムバージョンを識別するためのカスタムURIを選択する必要があります。このURIは、公式のJSONスキーマ仕様ドラフトの識別に使用されるURIの1つであってはならず、おそらく所有するドメイン名を含める必要があります。$schemaキーワードでこのURIを使用すると、スキーマがカスタムバージョンを使用していることを宣言できます。

ガイドライン

JSONスキーマの強みの1つは、JSONで記述でき、さまざまな環境で使用できることです。たとえば、フロントエンドとバックエンドの両方のHTMLフォーム検証に使用できます。カスタム語彙を使用する場合の問題は、スキーマを使用するすべての環境で、語彙のキーワードを評価する方法を理解する必要があることです。メタスキーマを使用して、スキーマが正しく記述されていることを確認できますが、各実装は、語彙のキーワードを評価する方法を理解するためにカスタムコードを必要とします。

メタデータキーワードは、検証に影響を与えないため、最も相互運用性があります。たとえば、unitsキーワードを追加できます。これは、準拠したバリデーターで常に期待どおりに機能します。

スキーマ

{ "type": "number", "units": "kg"}

データ

42

スキーマに準拠

データ

"42"

スキーマに準拠していません

カスタムキーワードの次の最適な候補は、他のスキーマを適用せず、既存のキーワードの動作を変更しないキーワードです。 isEven キーワードがその例です。ブラウザでの HTML フォームの検証など、ある程度の検証が全く検証しないよりも優れているコンテキストでは、このスキーマは期待できる範囲で適切に機能します。完全な検証は依然として必要であり、カスタムキーワードを理解するバリデーターを使用する必要があります。

スキーマ

{ "type": "integer", "isEven": true}

データ

2

スキーマに準拠

バリデーターがisEvenを理解しないため、これはパスします。

データ

3

スキーマに準拠

スキーマは、isEvenを理解しないため、完全に損なわれているわけではありません。

データ

"3"

スキーマに準拠していません

相互運用性が最も低いカスタムキーワードのタイプは、他のスキーマを適用するか、既存のキーワードの動作を変更するものです。例としては、プロパティを宣言して必須にするrequiredPropertiesなどがあります。この例は、カスタムキーワードを理解しないバリデーターで評価した場合に、スキーマがほぼ完全に役に立たなくなることを示しています。これは、requiredPropertiesがキーワードとして悪いアイデアであることを必ずしも意味するわけではなく、カスタムキーワードを理解しないコンテキストでスキーマを使用する必要がある場合に、それが適切な選択肢ではないということです。

スキーマ

{ "type": "object", "requiredProperties": { "foo": { "type": "string" } }}

データ

{ "foo": "bar" }

スキーマに準拠

requiredPropertiesが理解されないため、これはパスします。

データ

{}

スキーマに準拠

requiredPropertiesが理解されないため、これはパスします。

データ

{ "foo": 42 }

スキーマに準拠