Skip to content

Backport (3.0.4) of merge resolution from #3846 #3880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 6, 2024
Merged

Backport (3.0.4) of merge resolution from #3846 #3880

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
726929f
Further clarify discriminator usage (3.0.4)
handrews May 19, 2024
1308aa8
Use "discriminating value" consistently
handrews May 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions versions/3.0.4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,8 @@ When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such

If the same JSON/YAML object is parsed multiple times and the respective contexts require it to be parsed as _different_ Object types, the resulting behavior is _implementation defined_, and MAY be treated as an error if detected. An example would be referencing an empty Schema Object under `#/components/schemas` where a Path Item Object is expected, as an empty object is valid for both types. For maximum interoperability, it is RECOMMENDED that OpenAPI Description authors avoid such scenarios.

#### <a name="resolvingImplicitConnections"></a>Resolving Implicit Connections

### <a name="dataTypes"></a>Data Types

Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2).
Expand Down Expand Up @@ -2644,7 +2646,7 @@ components:
]
},
"Cat": {
"description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
"description": "A representation of a cat. Note that `Cat` will be used as the discriminating value.",
"allOf": [
{
"$ref": "#/components/schemas/Pet"
Expand All @@ -2671,7 +2673,7 @@ components:
]
},
"Dog": {
"description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
"description": "A representation of a dog. Note that `Dog` will be used as the discriminating value.",
"allOf": [
{
"$ref": "#/components/schemas/Pet"
Expand Down Expand Up @@ -2713,7 +2715,7 @@ components:
required:
- name
- petType
Cat: # "Cat" will be used as the discriminator value
Cat: # "Cat" will be used as the discriminating value
description: A representation of a cat
allOf:
- $ref: '#/components/schemas/Pet'
Expand All @@ -2729,7 +2731,7 @@ components:
- aggressive
required:
- huntingSkill
Dog: # "Dog" will be used as the discriminator value
Dog: # "Dog" will be used as the discriminating value
description: A representation of a dog
allOf:
- $ref: '#/components/schemas/Pet'
Expand All @@ -2747,12 +2749,14 @@ components:

#### <a name="discriminatorObject"></a>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 by implicitly or explicitly associating the possible values of a named property with alternative schemas.
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.
This hint can be used to aid in serialization, deserialization, and validation.
The Discriminator Object does this by implicitly or explicitly associating the possible values of a named property with alternative schemas.

##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="propertyName"></a>propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value.
<a name="propertyName"></a>propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminating value. This property SHOULD be required in the payload schema, as the behavior when the property is absent is undefined.
<a name="discriminatorMapping"></a> mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or URI references.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Surprising: we don't explicitly allow specification extensions here in 3.0.x?

Copy link
Member Author

@handrews handrews Jun 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I was surprised enough to check 3.0.3 and 3.0.0 to be sure, and we do not allow them.

##### Conditions for Using the Discriminator Object
Expand All @@ -2776,6 +2780,8 @@ However, the exact nature of such conversions are implementation-defined.

##### <a name="discriminatorExamples"></a>Examples

For these examples, assume all schemas are in the entry OpenAPI document; for handling of `discriminator` in referenced documents see [Resolving Implicit Connections](#resolvingImplicitConnections).

In OAS 3.0, a response payload MAY be described to be exactly one of any number of types:

```yaml
Expand Down Expand Up @@ -2826,7 +2832,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.
Here the discriminating value of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `#/components/schemas/dog`. If the discriminating value does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail.

When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload.

Expand Down