Skip to content

Commit bde8f97

Browse files
committed
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.
1 parent 4707ffc commit bde8f97

File tree

1 file changed

+8
-4
lines changed

1 file changed

+8
-4
lines changed

versions/3.1.1.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2696,7 +2696,11 @@ components:
26962696
26972697
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.
26982698

2699-
When using the discriminator, _inline_ schemas will not be considered.
2699+
`discriminator` uses a schema's "name" to automatically map a property value to
2700+
a schema. The schema's "name" is the property name used when declaring the
2701+
schema as a component. For example, the name of the schema at
2702+
`#/components/schemas/Cat` is "Cat". Therefore, when using `discriminator`,
2703+
_inline_ schemas will not be considered because they don't have a "name".
27002704

27012705
##### Fixed Fields
27022706
Field Name | Type | Description
@@ -2758,7 +2762,7 @@ MyResponseType:
27582762
monster: 'https://gigantic-server.com/schemas/Monster/schema.json'
27592763
```
27602764

2761-
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.
2765+
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.
27622766

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

@@ -2815,7 +2819,7 @@ a payload like this:
28152819
}
28162820
```
28172821

2818-
will indicate that the `Cat` schema be used. Likewise this schema:
2822+
will indicate that the `#/components/schemas/Cat` schema be used. Likewise this payload:
28192823

28202824
```json
28212825
{
@@ -2824,7 +2828,7 @@ will indicate that the `Cat` schema be used. Likewise this schema:
28242828
}
28252829
```
28262830

2827-
will map to `Dog` because of the definition in the `mapping` element.
2831+
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`.
28282832

28292833

28302834
#### <a name="xmlObject"></a>XML Object

0 commit comments

Comments
 (0)