From 4707ffc45bcd2a31ccdea440ea8387327301a4af Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Sat, 12 Jun 2021 12:15:17 -0700 Subject: [PATCH 01/12] Discriminator: Cleanup intro description This language seems to describe the value of the `discriminator` keyword to be an "object name" (whatever that means) rather than an object. --- versions/3.1.1.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 3c0c0a8af1..9313698a46 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2332,7 +2332,8 @@ The OpenAPI Specification's base vocabulary is comprised of the following keywor Field Name | Type | Description ---|:---:|--- -discriminator | [Discriminator Object](#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](#schemaComposition) for more details. +discriminator | [Discriminator +Object](#discriminatorObject) | Adds support for polymorphism. The discriminator is used to determine which of a set of schemas a payload is expected to satisfy. See [Composition and Inheritance](#schemaComposition) for more details. xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.

**Deprecated:** The `example` property has been deprecated in favor of the JSON Schema `examples` keyword. Use of `example` is discouraged, and later versions of this specification may remove it. @@ -2345,13 +2346,8 @@ The OpenAPI Specification allows combining and extending model definitions using `allOf` takes an array of object definitions that are validated *independently* but together compose a single object. While composition offers model extensibility, it does not imply a hierarchy between the models. -To support polymorphism, the OpenAPI Specification adds the `discriminator` field. -When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model. -As such, the `discriminator` field MUST be a required field. -There are two ways to define the value of a discriminator for an inheriting instance. -- Use the schema name. -- Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. -As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. +To support polymorphism, the OpenAPI Specification adds the `discriminator` keyword. +When used, the `discriminator` will indicate the name of the property that decides which schema definition validates the structure of the model. ###### XML Modeling From bde8f9723f595f6b2836e5650aef6f004394325e Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Sat, 12 Jun 2021 13:23:38 -0700 Subject: [PATCH 02/12] Discriminator: Define "schema name" and add clarifications The `discriminator` keyword uses the concept of "schema names", but what that means is never defined. There is no concept of a schema having a name is JSON Schema. They only have URIs. I also added some clarifications where the use of schema names got confusing. --- versions/3.1.1.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 9313698a46..ac0ab869d7 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2696,7 +2696,11 @@ components: When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it. -When using the discriminator, _inline_ schemas will not be considered. +`discriminator` uses a schema's "name" to automatically map a property value to +a schema. The schema's "name" is the property name used when declaring the +schema as a component. For example, the name of the schema at +`#/components/schemas/Cat` is "Cat". Therefore, when using `discriminator`, +_inline_ schemas will not be considered because they don't have a "name". ##### Fixed Fields Field Name | Type | Description @@ -2758,7 +2762,7 @@ MyResponseType: monster: 'https://gigantic-server.com/schemas/Monster/schema.json' ``` -Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. +Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) `#/components/schemas/dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. @@ -2815,7 +2819,7 @@ a payload like this: } ``` -will indicate that the `Cat` schema be used. Likewise this schema: +will indicate that the `#/components/schemas/Cat` schema be used. Likewise this payload: ```json { @@ -2824,7 +2828,7 @@ will indicate that the `Cat` schema be used. Likewise this schema: } ``` -will map to `Dog` because of the definition in the `mapping` element. +will map to `#/components/schemas/Dog` because the `dog` entry in the `mapping` element maps to `Dog` which is the schema name for `#/components/schemas/Dog`. #### XML Object From 314a7569a46f6150b91a39b0d156844a4cccb4e5 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Sat, 12 Jun 2021 14:45:55 -0700 Subject: [PATCH 03/12] Discriminator: Can't be a hint and a shortcut The `discriminator` keyword can't be a hint and a shortcut. I tried here to modify any language that might suggest that `discriminator` overrides the behavior of `anyOf`/`oneOf` in any way. --- versions/3.1.1.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index ac0ab869d7..002aa27f90 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2347,7 +2347,7 @@ The OpenAPI Specification allows combining and extending model definitions using While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the `discriminator` keyword. -When used, the `discriminator` will indicate the name of the property that decides which schema definition validates the structure of the model. +When used, the `discriminator` will indicate the name of the property that hints which schema definition is expected to validate the structure of the model. ###### XML Modeling @@ -2694,7 +2694,7 @@ components: #### Discriminator Object -When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it. +When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The `discriminator` keyword is used to inform the consumer of the document which of the alternatives is expected or preferred. `discriminator` uses a schema's "name" to automatically map a property value to a schema. The schema's "name" is the property name used when declaring the @@ -2722,8 +2722,7 @@ MyResponseType: - $ref: '#/components/schemas/Lizard' ``` -which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use: - +which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Evaluating a `oneOf` can be a costly operation, so `discriminator` MAY be used as a "hint" to improve the efficiency of validation and selection of the matching schema. The `discriminator` keyword can not change the validation result of the `oneOf`, it can only help make the evaluation more efficient and provide better error messaging. We can then describe exactly which field tells us which schema is expected to match the instance: ```yaml MyResponseType: @@ -2744,7 +2743,7 @@ The expectation now is that a property with name `petType` _MUST_ be present in } ``` -Will indicate that the `Cat` schema be used in conjunction with this payload. +Will indicate that the `Cat` schema is the alternative that is expected to match this payload. In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used: @@ -2764,7 +2763,7 @@ MyResponseType: Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) `#/components/schemas/dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. -When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. +When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity for serializers/deserializers where multiple schemas may satisfy a single payload. In both the `oneOf` and `anyOf` use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an `allOf` construct may be used as an alternate schema. @@ -2819,7 +2818,7 @@ a payload like this: } ``` -will indicate that the `#/components/schemas/Cat` schema be used. Likewise this payload: +will indicate that the `#/components/schemas/Cat` schema is expected to match. Likewise this payload: ```json { From 19ea81cc8ef0c7cd8a14b31c9b114050c23004dd Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Sat, 12 Jun 2021 14:48:21 -0700 Subject: [PATCH 04/12] Discriminator: Improve final example This example was super confusing, which is mostly because it doesn't indicate which schema the payload examples are being applied to. So, I added the schema and an explanation of what is happening. --- versions/3.1.1.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 002aa27f90..d9dbeaeef4 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2772,6 +2772,11 @@ For example: ```yaml components: schemas: + MyResponseType: + oneOf: + - $ref: '#/components/schemas/Cat' + - $ref: '#/components/schemas/Dog' + - $ref: '#/components/schemas/Lizard' Pet: type: object required: @@ -2809,7 +2814,12 @@ components: type: boolean ``` -a payload like this: +The `MyResponseType` schema will use the discriminator defined by the `Pet` +schema because it is part of the `Cat`, `Dog`, and `Lizard` schemas in the +`oneOf`. The behavior if not all schemas define a `discriminator` and they are +not all the same is undefined. + +Validated against the `MyResponseType` schema, a payload like this: ```json { From 4708f4aa1e815e45c91b487d46d376bb4473294f Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Mon, 14 Jun 2021 12:42:54 -0700 Subject: [PATCH 05/12] Discriminator: Schema name only applies to OAS documents Co-authored-by: Mike Ralphson --- versions/3.1.1.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index d9dbeaeef4..f7f447e1fd 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2698,9 +2698,10 @@ When request bodies or response payloads may be one of a number of different sch `discriminator` uses a schema's "name" to automatically map a property value to a schema. The schema's "name" is the property name used when declaring the -schema as a component. For example, the name of the schema at -`#/components/schemas/Cat` is "Cat". Therefore, when using `discriminator`, -_inline_ schemas will not be considered because they don't have a "name". +schema as a component in an OpenAPI document. For example, the name of the +schema at `#/components/schemas/Cat` is "Cat". Therefore, when using +`discriminator`, _inline_ schemas will not be considered because they don't have +a "name". ##### Fixed Fields Field Name | Type | Description From 0ae0968d5d7b3c1292465b595a7d49e9d2e940b1 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Tue, 15 Jun 2021 10:56:52 -0700 Subject: [PATCH 06/12] Discriminator: Add paragraph on schema name scoping Co-authored-by: Mike Ralphson --- versions/3.1.1.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index f7f447e1fd..3cf1046930 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2703,6 +2703,10 @@ schema at `#/components/schemas/Cat` is "Cat". Therefore, when using `discriminator`, _inline_ schemas will not be considered because they don't have a "name". +Schema names are scoped to the OpenAPI document they are defined in. That means +if OpenAPI document "A" references a schema in OpenAPI document "B", the schema +names in "A" aren't considered when evaluating the referenced schema in "B". + ##### Fixed Fields Field Name | Type | Description ---|:---:|--- From a76933b900fa93ba662ab78fb1ef2bfbb3f42ebf Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Sat, 12 Feb 2022 13:07:22 -0800 Subject: [PATCH 07/12] Make it more clear that `discriminator` is not for validation Co-authored-by: Darrel --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 3cf1046930..545b968a2d 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2727,7 +2727,7 @@ MyResponseType: - $ref: '#/components/schemas/Lizard' ``` -which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Evaluating a `oneOf` can be a costly operation, so `discriminator` MAY be used as a "hint" to improve the efficiency of validation and selection of the matching schema. The `discriminator` keyword can not change the validation result of the `oneOf`, it can only help make the evaluation more efficient and provide better error messaging. We can then describe exactly which field tells us which schema is expected to match the instance: +which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Evaluating a `oneOf` can be a costly operation, so `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` keyword can not change the validation result of the `oneOf`, it can only help make the evaluation more efficient and provide better error messaging. We can then describe exactly which field tells us which schema is expected to match the instance: ```yaml MyResponseType: From a9873a479993006943c42a24156c2845ed624319 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Sat, 12 Feb 2022 13:11:20 -0800 Subject: [PATCH 08/12] propertyName must be required in the schema --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 545b968a2d..6641682b89 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2710,7 +2710,7 @@ names in "A" aren't considered when evaluating the referenced schema in "B". ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. +propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. This property MUST be required in the payload schema. mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references. This object MAY be extended with [Specification Extensions](#specificationExtensions). From 1924bf004fa606c36d092f0acbad36ff910d053c Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Mon, 27 Mar 2023 13:27:53 -0700 Subject: [PATCH 09/12] Apply suggestions from code review Co-authored-by: Ralf Handl --- versions/3.1.1.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 6641682b89..0aa8cb5db2 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2332,8 +2332,7 @@ The OpenAPI Specification's base vocabulary is comprised of the following keywor Field Name | Type | Description ---|:---:|--- -discriminator | [Discriminator -Object](#discriminatorObject) | Adds support for polymorphism. The discriminator is used to determine which of a set of schemas a payload is expected to satisfy. See [Composition and Inheritance](#schemaComposition) for more details. +discriminator | [Discriminator Object](#discriminatorObject) | Adds support for polymorphism. The discriminator is used to determine which of a set of schemas a payload is expected to satisfy. See [Composition and Inheritance](#schemaComposition) for more details. xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.

**Deprecated:** The `example` property has been deprecated in favor of the JSON Schema `examples` keyword. Use of `example` is discouraged, and later versions of this specification may remove it. @@ -2727,7 +2726,7 @@ MyResponseType: - $ref: '#/components/schemas/Lizard' ``` -which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Evaluating a `oneOf` can be a costly operation, so `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` keyword can not change the validation result of the `oneOf`, it can only help make the evaluation more efficient and provide better error messaging. We can then describe exactly which field tells us which schema is expected to match the instance: +which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Evaluating a `oneOf` can be a costly operation, so `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` keyword cannot change the validation result of the `oneOf`, it can only help make the evaluation more efficient and provide better error messaging. We can then describe exactly which field tells us which schema is expected to match the instance: ```yaml MyResponseType: From 6ea52f235832ba34d4ad04c8f5dc696c116ea899 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Thu, 21 Mar 2024 11:09:38 -0700 Subject: [PATCH 10/12] Apply suggestions from code review Co-authored-by: Adam Altman --- versions/3.1.1.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 0aa8cb5db2..2ca725f33f 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2346,7 +2346,7 @@ The OpenAPI Specification allows combining and extending model definitions using While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the `discriminator` keyword. -When used, the `discriminator` will indicate the name of the property that hints which schema definition is expected to validate the structure of the model. +When used, the `discriminator` indicates the name of the property that hints which schema definition is expected to validate the structure of the model. ###### XML Modeling @@ -2693,7 +2693,7 @@ components: #### Discriminator Object -When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation. The `discriminator` keyword is used to inform the consumer of the document which of the alternatives is expected or preferred. +When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object gives a hint about the expected schema of the document. It can be used to aid in serialization, deserialization, and validation. `discriminator` uses a schema's "name" to automatically map a property value to a schema. The schema's "name" is the property name used when declaring the @@ -2726,7 +2726,7 @@ MyResponseType: - $ref: '#/components/schemas/Lizard' ``` -which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Evaluating a `oneOf` can be a costly operation, so `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` keyword cannot change the validation result of the `oneOf`, it can only help make the evaluation more efficient and provide better error messaging. We can then describe exactly which field tells us which schema is expected to match the instance: +which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Evaluating a `oneOf` can be a costly operation, so `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` keyword cannot change the validation result of the `oneOf`, it can only help make the evaluation more efficient and provide better error messaging. We can specify the exact field that tells us which schema is expected to match the instance: ```yaml MyResponseType: @@ -2747,7 +2747,7 @@ The expectation now is that a property with name `petType` _MUST_ be present in } ``` -Will indicate that the `Cat` schema is the alternative that is expected to match this payload. +Will indicate that the `Cat` schema is expected to match this payload. In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used: From eb5ddeea7a708678f1953d58aff0cd751b6ec374 Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Thu, 21 Mar 2024 11:27:22 -0700 Subject: [PATCH 11/12] Remove anything deemed controversial --- versions/3.1.1.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 2ca725f33f..2d552844a8 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2702,10 +2702,6 @@ schema at `#/components/schemas/Cat` is "Cat". Therefore, when using `discriminator`, _inline_ schemas will not be considered because they don't have a "name". -Schema names are scoped to the OpenAPI document they are defined in. That means -if OpenAPI document "A" references a schema in OpenAPI document "B", the schema -names in "A" aren't considered when evaluating the referenced schema in "B". - ##### Fixed Fields Field Name | Type | Description ---|:---:|--- @@ -2776,11 +2772,6 @@ For example: ```yaml components: schemas: - MyResponseType: - oneOf: - - $ref: '#/components/schemas/Cat' - - $ref: '#/components/schemas/Dog' - - $ref: '#/components/schemas/Lizard' Pet: type: object required: @@ -2818,12 +2809,7 @@ components: type: boolean ``` -The `MyResponseType` schema will use the discriminator defined by the `Pet` -schema because it is part of the `Cat`, `Dog`, and `Lizard` schemas in the -`oneOf`. The behavior if not all schemas define a `discriminator` and they are -not all the same is undefined. - -Validated against the `MyResponseType` schema, a payload like this: +Validated against the `Pet` schema, a payload like this: ```json { From 2d940c5dfc3ec16e3347fbceff9e2c395e48f29b Mon Sep 17 00:00:00 2001 From: Jason Desrosiers Date: Mon, 25 Mar 2024 11:45:24 -0700 Subject: [PATCH 12/12] Update versions/3.1.1.md Co-authored-by: Mike Kistler --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 2d552844a8..d78215d3bc 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2722,7 +2722,7 @@ MyResponseType: - $ref: '#/components/schemas/Lizard' ``` -which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Evaluating a `oneOf` can be a costly operation, so `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` keyword cannot change the validation result of the `oneOf`, it can only help make the evaluation more efficient and provide better error messaging. We can specify the exact field that tells us which schema is expected to match the instance: +which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Deserialization of a `oneOf` can be a costly operation, as it requires determining which schema matches the payload and thus should be used in deserialization. This problem also exists for `anyOf` schemas. A `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` keyword cannot change the validation result of the `oneOf`, it can only help make the deserialization more efficient and provide better error messaging. We can specify the exact field that tells us which schema is expected to match the instance: ```yaml MyResponseType: