アノテーション

JSON Schemaには、厳密には検証には使用されないものの、スキーマの一部を記述するために使用されるいくつかのキーワードが含まれています。これらの「アノテーション」キーワードは必須ではありませんが、良いプラクティスとして推奨されており、スキーマを「自己文書化」することができます。

アノテーションキーワードは、任意のスキーマまたはサブスキーマで使用できます。他のキーワードと同様に、一度だけ使用できます。

titleおよびdescriptionキーワードは文字列である必要があります。「title」は短いものが望ましく、「description」はスキーマによって記述されたデータの目的についてのより長い説明を提供します。

defaultキーワードはデフォルト値を指定します。この値は、検証プロセス中に欠落値を埋めるために使用されるわけではありません。ドキュメントジェネレーターやフォームジェネレーターなどの非検証ツールは、この値を使用して、ユーザーに値の使用方法に関するヒントを与える場合があります。ただし、defaultは通常、値が欠落している場合、その値が存在し、デフォルト値が設定されている場合と意味的に同じであることを表すために使用されます。defaultの値は、それが存在するスキーマに対して検証される必要がありますが、必須ではありません。

ドラフト6の新機能

examplesキーワードは、スキーマに対して検証される例の配列を提供する場所です。これは検証には使用されませんが、スキーマの効果と目的を読者に説明するのに役立つ場合があります。各エントリは、それが存在するスキーマに対して検証される必要がありますが、必須ではありません。examples配列にdefault値を複製する必要はありません。なぜなら、defaultは別の例として扱われるからです。

ドラフト7の新機能

ブール値キーワードreadOnlyとwriteOnlyは、通常、APIコンテキストで使用されます。readOnlyは、値を変更すべきではないことを示します。値の変更を伴うPUTリクエストが400 Bad Requestレスポンスになることを示すために使用できます。writeOnlyは、値を設定できるが、非表示になることを示します。値はPUTリクエストで設定できますが、GETリクエストでレコードを取得する際には含まれないことを示すために使用できます。

ドラフト2019-09の新機能

deprecatedキーワードは、キーワードが適用されるインスタンス値を使用すべきではなく、将来削除される可能性があることを示すブール値です。

スキーマ

{ "title": "Match anything", "description": "This is a schema that matches anything.", "default": "Default value", "examples": [ "Anything", 4035 ], "deprecated": true, "readOnly": true, "writeOnly": false}