JSON Schema実装全体にわたる共通インターフェース

JSON Schemaは非常に広く使用されており、ほぼ同じくらい広く実装されています。JSON Schema検証の実装は、20以上の言語または環境で利用可能です。この普及率は、ユーザーの選択にとって素晴らしいことです。JSON Schemaを使用したいと考えている人は、ターゲット環境に適した実装を見つけることができるとほぼ確信できます。

しかし、コミュニティサポートに関しては、特定のライブラリまたは実装でさまざまなJSON Schema操作を実行する方法を知ることは難しい場合があります。それぞれがわずかに異なる（またはかなり異なる）APIを持っている可能性があるためです。これは、仕様自体では必ずしも規定または要求されていないが、JSON Schemaを使用するために*実際には*一般的で、便利で、さらには必要な動作を検討する場合に特に困難になる可能性があります。このページは、これらの*一般的な操作*の多くを文書化し、既存のJSON Schemaエコシステム全体で多くの実装によって提供されるインターフェースを文書化するのに役立ちます。

それぞれについて、最初に仕様の用語を使用して操作に名前を付け、説明します。仕様の用語が利用できない場合は、簡潔でありながら正確を目指した用語を使用します。このページの目的は、重要なJSON Schema操作のリファレンスとなることと、特定の言語と実装のヘルプを調整することです。したがって、既知の場合は、実装全体で各インターフェースまたは機能の例を含めます。このページのセクションの順序は、必ずしも互いに対する重要度を示しているわけではありません。機能の省略（つまり、特定の実装で以下の方法が見つからない場合）は、実装が機能をサポートしていないことを必ずしも示しているわけではありませんが、ページの作成者によって簡単に見つけることができなかったことを意味する可能性があります。実装者からの貢献と修正、そしてドキュメントリンクは大歓迎です！

このページのいくつかのセクションをより正確にするために、以下で参照される可能性のある一連の*抽象型*が存在すると仮定します。これらは、特定のプログラミング言語または実装内で具体的な型を持ちます。String、Number、Boolean、Mapping、Callableなどのプレースホルダー型に加えて、JSON Schema関連の型には以下が含まれます。

スキーマ

JSON Schemaの型。JSON Schemaのダイアレクトによって異なる場合があります。JSON Schemaの一般的または現代的なバージョンでは、この型は基本的に任意のJSONオブジェクトとブール値の両方を表現できる必要があります。

インスタンス

JSONインスタンスの型。この型は基本的にAnyであるか、JSON Schemaが表現可能なJSONに適用できることを考えると、すべてのJSON値を表現できる型である必要があります。

ダイアレクト

JSONダイアレクトまたはダイアレクト識別子の型。ダイアレクトが実装内でそのURIまたは短い名前で表される場合、この型は単にStringである可能性があります。

EvaluationOptions

実装固有のカスタマイズ可能な動作とともに、「完全に準備された」スキーマとインスタンスの型。少なくとも、この型はSchema → InstanceまたはSchema × Instanceのいずれかです（実装がスキーマとインスタンスを一緒に取るのか、スキーマをコンパイルしてから検証するインスタンスを取る別の関数を生成するのかによって異なります）。少なくとも以下のようないくつかの方法でよりリッチになる可能性が非常に高いです。

• 外部スキーマの参照をサポートするために何らかの形式のスキーマリポジトリがサポートされる可能性が高いため、この型にはおそらく何らかのレジストリが含まれます。つまり、Mapping<URI, Schema> → Schema → ...です。
• 実装がどのJSON型がどの言語型に一致するかをカスタマイズすることをサポートしている場合（以下で説明など）、この型にはおそらくこのマッピングの表現が含まれます。つまり、Mapping<String, Callable[...]> → Schema → ...は、この評価中に各型が何にマップされるかをカプセル化します。
• 同様に、フォーマットアサーションの有効化のための特定のAPIがある場合、formatキーワードの動作の表現がコンテキストに存在します。
• 実装がダイアレクトの作成またはカスタマイズをサポートしている場合、特にスキーマが異なるダイアレクトにまたがるサブスキーマを含むことができる場合、コンテキストにはダイアレクトの何らかの表現が含まれます。例：Dialect → Schema → ...

結果

JSON Schema検証結果の型、つまり、特定のインスタンスがスキーマのもとで有効かどうかをカプセル化するオブジェクトです。この型は、実装や言語によっては単にブール値の場合があります。

注釈付き結果（ResultWithAnnotations）

URI

RFC 3986準拠のURIの型です。URIには複数の文字列表現が可能であり、正しいセマンティクスを持つためには正規化が必要となるため、この型は一般的に文字列と同じではありません。

このページは言語の壁を越えた懸念事項を扱っており、特に帯域外のエラーをどのように表現するか（例外、オプション型、ラッパー戻り値型、センチネル値、またはその他のメカニズムを介して）について、プログラミング言語によって異なる機能があるため、このページでは、明示的な帯域外エラーの表現を含む関数の型を表すための¹特定の表記法も導入しています。これらの型の解釈はプログラミング言語によって異なります。例を用いて上記を説明する方が簡単です。

x / yとして表される、浮動小数点数の除算関数を考えてみましょう。

この関数の型をFloat → Float → Float <!> DivideByZeroErrorと記述します。このシグネチャの解釈は、関数は2つの浮動小数点数を受け取り、浮動小数点数を返しますが、<!>は、DivideByZeroError（この場合は関数がゼロ除算を要求された場合）を伝播する可能性があることを示しています。

DivideByZeroErrorの具体的な manifestations は、プログラミング言語によって異なります。例外を持つ言語では、この関数は例外としてDivideByZeroErrorに相当するものを発生させる可能性があり、呼び出し元によって処理される必要があります。オプション型を持つ言語では、「正しい」型シグネチャは実際にはゼロ除算ケースを表すOption型でラップされている可能性があります（そのため、そのような言語の「真の」シグネチャはOption[Float → Float → Float]になります）。ラッパー戻り値型を持つ言語では、真の型シグネチャはResult<Float, DivideByZeroError>になる場合があります。ここで、返された値は正常な結果が含まれていることを確認するために検査する必要があり、ゼロ除算エラーは代わりに可能なエラー値です。「ジャンク」値を返す規則を持つ言語では、真の型は正確にFloat → Float → Floatになる場合があります。ゼロ除算時に任意の浮動小数点値が返され、それ以上の兆候はありません。

上記のすべての場合において、例外（対応するエラーまたはジャンク値）が発生した場合（対応して返された場合）、慣例により、通常の戻り値はプログラミング言語のメカニズムによって完全に存在しないか、意味がないと見なされます。

さらに、このページでは、一般に、特定のセクションで説明されている以外の理由でエラーが発生する可能性については、考慮または言及しません。たとえば、上記の除算の例では、実行時にそのような可能性が存在する動的型付け言語で文字列が提供された場合、他の種類のエラーが発生する可能性があります。そのため、「実際の」除算関数はFloat → Float → Float <!> DivideByZeroError | TypeErrorまたはさらに多くのエラーの可能性のように見える場合があります。JSON Schemaの場合、これは、以下に示すすべてのインターフェースが、仕様に従って有効ではないスキーマ、またはJSONデータモデルに適合しないスキーマなどが提供された場合を表す<!> InvalidSchema | NotValidJSON | ...を含む型を持っていることを意味する可能性がありますが、これらは暗黙的であると見なし、議論されているインターフェースに直接関連しない限り、明示的に言及しません。

インスタンス検証

インスタンス検証は、JSON Schemaの主要な機能の1つです。これは、特定のデータが特定のスキーマのもとで有効または無効と見なされるプロセスです。実装では、この検証を実行するために、以下の特定のインターフェースの1つ以上を提供する場合があります。

例外駆動型検証

型：EvaluationOptions → None <!> ValidationErrorまたはEvaluationOptions → Result <!> ValidationError

検証自体が失敗した場合に、言語固有の失敗または例外を発生させる検証API。成功した場合、このAPIは詳細を含む結果を返すか、単にサイレントに実行を継続する場合があります。

ブール値検証

型：EvaluationOptions → Boolean

スキーマのもとでのインスタンスの有効性を示す単純なブール値の結果を生成するAPI。

2引数検証

型：Schema × Instance → Result

スキーマとインスタンスを同時に受け取り、インスタンスが指定されたスキーマのもとで有効かどうかを示す結果を生成するAPI。

ある意味で、2引数検証はJSON Schema検証にとって最も単純なAPIです。これは、スキーマの反復使用や追加の計算を前提とせずに、指定されたインスタンスが指定されたスキーマのもとで有効かどうかを単純に尋ねます。

反復検証 / スキーマコンパイル

型：Schema → Instance → Result

繰り返し使用するためにスキーマを準備しようとするAPI。何らかの形式の事前最適化を実行し、多くのインスタンスを検証する際に繰り返す必要がないように、事前に一連の作業を実行する可能性があります（そして可能性が高いです）。

サブスキーマ検証

型：Schema × String × Instance → Result

指定されたスキーマ内に含まれる*サブスキーマ*に対してインスタンスを検証することをサポートするAPI。

サブスキーマは通常、JSONポインター、または同等の構文によって識別され、 $refキーワードを介してサブスキーマを参照する新しいスキーマを使用した検証とは対照的です。

注釈収集

型：EvaluationOptions → ResultWithAnnotations

指定されたスキーマとインスタンスを処理する際に生成された注釈を収集するAPI。

スキーマ検証

型：Schema → Result

スキーマ自体を、それが記述されているダイアレクトのもとで検証するAPI。このAPIは、ダイアレクトに対応するメタスキーマ（またはメタスキーマ）を使用する可能性がありますが、一般に、メタスキーマ内でチェックされていない条件下でもスキーマが無効にならないように、追加の作業を行う必要があります。

明示的なバージョン選択

型：Dialect → EvaluationOptions → Result

実装が、ダイアレクトを明示的に示していない（つまり、$schemaプロパティを宣言していない）スキーマが指定された場合に想定するダイアレクトを制御するAPI。

バージョン検出

型：Schema → Dialect

指定されたスキーマがどのダイアレクトで記述されているかを識別し、ダイアレクト自体、またはダイアレクト固有の検証関数を返すAPI。

型のカスタマイズ

JSON Schemaの型に対応する言語レベルの型を（再）設定し、さらに新しい型の定義を可能にするAPI。

文字列検証

型: String → String → Result

インスタンスとスキーマの両方が、デシリアライズされたJSONではなく、シリアライズされたJSON（文字列化されたJSON）として表現されている場合に、それらを使用してインスタンスを直接検証するAPI。

言語オブジェクト検証

型: EvaluationOptions → Result

インスタンスとスキーマの両方が言語レベルのオブジェクトにデシリアライズされているか、またはプログラムで言語レベルのオブジェクトとして直接構築されている場合に、それらを使用してインスタンスを検証するAPI。

format 検証

フォーマットアサーションの有効化

JSON Schemaボキャブラリの有効化によってのみ制御されない方言において、formatキーワードの動作を設定するAPI。

フォーマット登録

型: String × (Instance → Boolean)→EvaluationOptions`

通常はアサートするために使用される場合に、formatキーワードで使用する*新しい*フォーマットとその実装を登録できるAPI。

実装によっては、異なる方言に対して異なる利用可能なフォーマットのセットを登録できる場合があります。

フォーマットのクエリ

登録されている利用可能なフォーマットのセットをクエリまたは一覧表示するAPI。

直接フォーマット検証

型: String × Instance → Boolean

スキーマが存在しなくても、JSONのような値が特定のフォーマットを満たしているかどうかを直接チェックできるAPI。

スキーマリポジトリの設定

検証プロセス中に参照可能なスキーマのバンドルを設定するAPI。

外部識別スキーマ

1つ以上のURIをスキーマに関連付けるAPI。URIは、$idキーワード（または方言固有の同等のもの）によって内部的に示されません。

内部識別スキーマ

URIをスキーマに関連付けるAPI。URIは、スキーマ内の$idキーワード（または方言固有の同等のもの）の存在によって内部的に示されます。

スキーマディスカバリ

ルートスキーマを（再帰的に）クロールし、存在し識別可能なサブリソース（サブスキーマ）を検出し、それらのサブリソースのURIをさらに参照できるようにするAPI。

動的URI解決

レジストリに事前設定されていない参照に対して、任意の動的ルックアップ動作を可能にするAPI。

出力フォーマットの選択/生成

結果を生成するときに使用するJSON Schemaの出力フォーマットを設定するAPI、またはResultに基づいて特定の出力フォーマットを生成できるAPI。

ボキャブラリ登録

新しいJSON Schemaボキャブラリの作成を容易にするAPI。通常は、後で新しい方言を構築する際に使用されます。

方言の作成

新しいJSON Schema方言の作成を容易にするAPI。通常は、実装内でさらに使用できるように、何らかの方法で登録します。

失敗の詳細

特定の検証エラーの原因をプログラムでイントロスペクションできるAPI。少なくとも、エラーの原因となったキーワード、値、および個々のメッセージが含まれます。