JSONスキーマ用語集

このドキュメントでは、JSON Schemaコミュニティ内でよく見られる用語の簡単な説明をまとめています。

以下の多くの項目には正確な技術的定義がありますが、ここでは会話での使用方法の説明を優先し、詳細情報へのリンクを追加しています。このページは規範的であることを意図しておらず、完全に独創的な調査や説明を含むことを意図したものでもありません。JSON Schemaや、より広範な仕様で使われる正式な言葉にあまり馴染みのない人の理解を助けることを目的としています。（実際、以下の項目では、前述の理由から「規範的」のような用語そのものを避けるように努力しています。）

ここに定義されていると便利な用語に出会った場合は、問題を提起してリクエストしてください。

このページの項目は、アンカーリンク（例：https://json-schema.dokyumento.jp/learn/glossary.html#vocabulary）でリンクして、他の人と定義を共有することができます。

ダイアレクト

スキーマ内で使用できるキーワードのまとまりのあるコレクションであり、多くの場合、JSONスキーマ仕様のユースケース固有の単一リリースを表します。

ダイアレクト、特に2019-09および2020-12ダイアレクトは、ボキャブラリーのコレクションを通じて定義されることがよくあります。

各ダイアレクトはURI、つまりダイアレクト識別子によって識別され、スキーマは$schema キーワードで参照できます。これにより、スキーマがダイアレクトで記述されていることが識別され、その中で使用可能なキーワードとその意図された意味が示されます。

JSONスキーマ仕様では、多数のダイアレクトが定義されており、それぞれがダイアレクトの特定のユースケースに適したボキャブラリーを有効にします。これらのボキャブラリーは、メタスキーマで説明されています。

ドラフト

JSONスキーマ仕様の個々のリリース。

JSONスキーマのドラフトは、一般の人が「ドラフト」という言葉を使うように、暫定的な文書であることを意図したものではありません。

将来のドラフトで新しい動作や既存の動作の変更が導入される可能性がありますが、各ドラフトは完成したリリース済みのドキュメントであり、仕様の変更をまとめて実装と使用を目的としています。

ドラフトの現在のリストは、こちらにあります。

JSON

人間が読めるテキストとしてデータを表現および送信するために使用される、普及したデータ交換形式。JSONは非常に広く使用されており、JSONを読み書きできるパーサーは、実質的にすべての一般的なプログラミング言語に存在します。

JSON Schemaは、明確にJSONの上に構築されており、JSONのスキーマ自体は、JSON値を記述するJSONオブジェクトです。ただし、この2つは概念的なパズルのまったく異なる部分であり、JSONはデータの表現のための具体的な形式であり、JSON SchemaはJSON互換形式で記述されたデータをスキーマ化する方法です。

JSON形式はオープンな形式であり、独自のホームページを持ち、ECMAのECMA-404文書およびIETFのRFC-8259文書で仕様が公開されています。特に、JSON Schemaチームによって管理または開発されているわけではなく、単にこの形式を利用しているだけです。

JSON Hyper-Schema

JSON Hyper-SchemaはJSON Schemaを拡張し、JSONドキュメントにハイパーメディアコントロールを注釈するための語彙を提供します。この拡張機能により、JSONデータ上で実行できるリンクやアクションの説明が容易になり、ハイパーメディア駆動のAPIを開発するための強力なツールとなります。

JSON Hyper-Schemaの本質は、JSONデータ上で実行できるリンクとアクションを定義する能力にあります。これは、linksキーワードを使用することで実現され、動的でインタラクティブなデータ表現の作成を可能にします。例えば、ブログ記事を表すJSONドキュメントには、「author」プロパティが含まれる場合があります。このドキュメントを記述するJSON Hyper-Schemaには、インスタンス内の著者の識別子を使用して、著者のプロフィールへのリンクを作成するハイパーメディアコントロールのテンプレートを含めることができます。開発者はURLを手動で作成する必要がないため、シームレスなナビゲーションエクスペリエンスを提供することで、開発者のエクスペリエンスが向上します。

言い換えれば、JSON Hyper-Schemaは、ハイパーメディアコントロールを作成するための機能を追加することでJSON Schemaを拡張します。これにより、インタラクティブなAPIの作成が容易になり、既存のJSON HTTP APIとの互換性が確保され、シームレスな統合が維持されます。JSONドキュメントにインタラクティブなレイヤーを追加し、リモートのJSONリソースとのやり取りを容易にします。

JSONポインタ

JSONポインタは、JSONドキュメント内の指定された場所にある値を識別するための文字列構文です。ドキュメントの特定の部分を、取得または操作のために正確に参照するのに役立ちます。サブスキーマは、多くの場合、JSONポインタを使用して、包含リソース内の場所を指定することで識別されます。

キーワード

スキーマオブジェクト内に現れるプロパティ。

JSON Schema仕様は、インスタンスを記述するために使用できる、大規模なキーワードライブラリの動作を定義しています。

実装

歴史的に、「実装」という言葉は、特にバリデーター/アノテーター（仕様の範囲）と、他のさまざまな種類のJSON Schemaツールを記述するために使用されてきました。しかし、この曖昧さのため、推奨される会話上の用語は「ツール」であると決定しました。

インスタンス

スキーマによって記述されるべきJSONデータの一部。

JSON Schemaは、任意の型のJSON値（および、JSONとして適切に表現できる多くのJSONに似た形式の値）を記述するために使用できます。

JSON Schema仕様は、JSON仕様自体の範囲を超えて、インスタンス自体の構造について広範な仮定をしていません。特に、JSONオブジェクト内に独自の用途のためのプロパティを予約したり、JSON実装にすでに義務付けられている機能を超えて機能をサポートするようにJSONパーサーに要求したりすることはありません。

メタスキーマ

他のスキーマを記述することを目的とするスキーマ。

JSON Schemaは、JSONで記述されたスキーマを使用して、任意のインスタンスを記述するための言語を定義します。スキーマ自体がJSON値であるため、インスタンスとして扱われ、他のスキーマによって記述される可能性もあります。

この使用を表現するために、スキーマのスキーマを「メタスキーマ」と呼びます。

規範的

JSON Schemaおよびより広範な正式な仕様のコンテキストでは、標準化された動作の概要を示すドキュメント。これは、説明、簡略化、または意見を提供することを目的とした非規範的または情報提供ドキュメントとは異なります。

ドキュメントが規範的であるかどうかを区別することは、ドキュメントを使用する人に、その内容が他の規範的ドキュメントで説明されている動作に矛盾したり、拡張したりすることが許可されているかどうかを明確にすることを目的としています。JSON Schemaの規範的ドキュメントには、特に仕様が含まれます。例えば、このページは規範的ドキュメントではないため、仕様でまだカバーされていない新しいJSON Schemaの動作を規定することはできません。

参照

• Mozilla Glossaryの規範的および非規範的、およびそのリンク

スキーマ

JSON Schema仕様の規定された構造に従って記述されたドキュメント。これを使用してインスタンスを記述できます。

どのスキーマが適合しているかを構成するルール、およびインスタンスを検証する際の動作を制御するルールは、JSON Schema仕様によって定義されています。

厳密に言えば、仕様によれば、スキーマ自体はJSONドキュメントですが、YAMLなど、JSONに簡単に変換できる他の言語で作成または保守されることが一般的です。

仕様の最近のドラフトでは、スキーマはJSONオブジェクトまたはJSONブール値のいずれかです。

サブスキーマ

それ自体が、周囲の親スキーマ内に含まれているスキーマ。スキーマ自体と同様に、JSON Schemaの最近のドラフトでは、サブスキーマはJSONオブジェクトまたはJSONブール値のいずれかです。

JSON Schema仕様とそのダイアレクト内では、多くのキーワードが値の一部としてサブスキーマを取得します。例えば、notキーワードはサブスキーマ値を取得し、その結果を反転させ、サブスキーマが失敗した場合は常に成功するため、インスタンス12は{"type": "string"}では無効ですが、{"not": {"type": "string"}}では有効です。ここで、{"type": "string"}は完全なスキーマに含まれるサブスキーマです。

一部のサブスキーマは、親スキーマ内のより複雑なネストされた場所に表示される場合があります。例えば、allOfキーワードは、複数のサブスキーマの配列を取得し、すべてのサブスキーマが個別に成功した場合は常に成功します。

（その内容に基づいて）スキーマであると見えるものが、実際にはサブスキーマであるかどうかは、親スキーマ内の位置に関するコンテキストや知識がないと、最初は誤解を招く可能性があります。特に、上記の例では、{"type": "string"}はより大きなスキーマのサブスキーマでしたが、スキーマ{"const": {"type": "string"}}では、サブスキーマではありません。値として同じように見えても、インスタンスを特定の予期される値と比較するconstキーワードは、サブスキーマを値として取得しません。その値は特定の意味を持たない不透明な値です（このスキーマでは、数値12は無効ですが、正確なインスタンス{"type": "string"}は有効です）。より簡単に言えば、特定の値がサブスキーマであるかどうかは、親スキーマ内の正確な位置によって異なり、値の解釈はその値が存在するキーワードの定義された動作に依存します。

サブスキーマ自体にサブサブスキーマが含まれる場合がありますが、一般的には、ネストのレベルに関係なく「サブスキーマ」という用語を使用し、必要に応じて、どのより大きなスキーマが親スキーマであるかをさらに明確にします。

ツール

JSON Schemaツール（または口語的に「ツール」）は、何らかの方法でスキーマを操作または評価するためのソフトウェアアプリケーションまたはライブラリです。

以下はツールと見なされます。

• バリデーターライブラリ
• CLIバリデーター
• スキーマまたはコードジェネレーター
• UIフォームジェネレーター

例えば、構成ファイルやWebリクエストを検証するなど、内部でJSON Schemaを使用し、その機能を何らかの方法で公開しないアプリケーションは、ツールとは見なされません。

検証結果

JSON Schemaのコンテキストでの検証結果は、JSON Schema全体をインスタンスドキュメント全体に適用した結果を指します。この結果には、ブール値のアサーションだけでなく、エラーメッセージ、エラーコード、詳細な検証レポートなど、さまざまな出力形式が含まれる場合があります。これは、インスタンスドキュメントがスキーマで指定されたルールと制約に準拠しているかどうかを示します。検証結果は、インスタンスドキュメントがスキーマに対する検証に合格したか失敗したかを示します。

語彙

再利用を容易にするためにグループ化された、密接に関連するキーワードのコレクション。

語彙は、そのキーワードのセマンティクスを、語彙の実装者とユーザーに適した方法で説明する散文ドキュメントまたは仕様によって指定されます。多くの場合、キーワードの構文を定義するメタスキーマ（または複数のメタスキーマ）も含まれます。

誰でも語彙を作成して公開することができ、実装には通常、追加の語彙とそのキーワードのサポートでそれ自体を拡張するための機能が含まれます。JSON Schema仕様には、定義されている各キーワードをカバーする多くの語彙が含まれています。

JSON Schemaのいくつかのダイアレクトでは、$vocabularyキーワードを使用して、語彙で定義されたキーワードをダイアレクトに含めることができるほか、ダイアレクトで記述されたスキーマを処理できるようにするために、実装が語彙を具体的に認識する必要があるかどうかを示すことができます。

参照

• json-schema-vocabularies、既知のサードパーティのJSON Schema語彙を収集するリポジトリ