識別子オブジェクト
リクエストの本文またはレスポンスのペイロードが多数の異なるスキーマの 1 つである場合、discriminatorオブジェクトを使用してシリアル化、逆シリアル化、および検証を支援できます。識別子は、スキーマ内の特定のオブジェクトであり、それに関連付けられた値に基づいて、ドキュメントの消費者に代替スキーマを通知するために使用されます。
識別子を使用する場合、インラインスキーマは考慮されません。
固定フィールド
| フィールド名 | タイプ | 説明 |
|---|---|---|
| プロパティ名 | string | 必須。識別子の値を保持するペイロード内のプロパティの名前。 |
| マッピング | Map[ string, string] | ペイロード値とスキーマ名または参照の間のマッピングを保持するオブジェクト。 |
このオブジェクトは、仕様拡張機能を使用して拡張できます。
識別子オブジェクトは、複合キーワードoneOf、allOf 、anyOfのいずれかを使用する場合にのみ有効です。
OAS 3.0 では、応答ペイロードは、次のいずれかのタイプのいずれかであるように記述できます (MAY)。
MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard'
これは、ペイロードが、検証により、Cat 、Dog、またはLizardで記述されたスキーマの 1 つと正確に一致しなければならないことを意味します。この場合、ディスクリミネーターは、スキーマの複雑さに応じて、コストのかかる操作となる可能性がある、一致するスキーマの検証と選択をショートカットするための「ヒント」として機能してもよい(MAY)。次に、どのフィールドがどのスキーマを使用するかを正確に記述することができます。
MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' discriminator: propertyName: petType
現在、petType名前を持つプロパティが応答ペイロードに存在する必要があり、その値は OAS ドキュメントで定義されているスキーマの名前に対応することが 期待されています。したがって、応答ペイロードは次のようになります。
{ "id": 12345, "petType": "Cat"}
Catスキーマがこのペイロードと組み合わせて使用されることを示します。
識別子フィールドの値がスキーマ名と一致しない、または暗黙的なマッピングが不可能なシナリオでは、オプションのmapping定義を使用してもよい(MAY)。
MyResponseType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json' discriminator: propertyName: petType mapping: dog: '#/components/schemas/Dog' monster: 'https://gigantic-server.com/schemas/Monster/schema.json'
ここで、 dogの識別子の値は、のデフォルト (暗黙的) 値ではなく、schema #/components/schemas/Dogにマップされます。識別子dogの値が暗黙的または明示的なマッピングに一致しない場合、スキーマを決定できず、検証は失敗する必要があります(SHOULD)。マッピング キーは文字列値である必要がありますが、ツールは比較のために応答値を文字列に変換してもよいです。
anyOf構造と組み合わせて使用すると、識別子の使用により、複数のスキーマが単一のペイロードを満たす可能性がある曖昧さを回避できます。
oneOfとanyOfの両方の使用例で、考えられるすべてのスキーマを明示的にリストする必要があります。冗長性を避けるために、識別子を親スキーマ定義に追加してもよく、allOf構造内の親スキーマを構成するすべてのスキーマを代替スキーマとして使用してもよい。
例えば：
components: schemas: Pet: type: object required: - petType properties: petType: type: string discriminator: propertyName: petType mapping: dog: Dog Cat: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Cat` properties: name: type: string Dog: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Dog` properties: bark: type: string Lizard: allOf: - $ref: '#/components/schemas/Pet' - type: object # all other properties specific to a `Lizard` properties: lovesRocks: type: boolean
このようなペイロード:
{ "petType": "Cat", "name": "misty"}
Catスキーマが使用されることを示します。同様に、このスキーマは次のようになります。
{ "petType": "dog", "bark": "soft"}
mapping要素内の定義により、Dogにマップされます。