Skip to content

Commit eae07a8

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 5ca7a28 commit eae07a8

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
@@ -2701,7 +2701,11 @@ components:
27012701
27022702
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.
27032703

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

27062710
##### Fixed Fields
27072711
Field Name | Type | Description
@@ -2763,7 +2767,7 @@ MyResponseType:
27632767
monster: 'https://gigantic-server.com/schemas/Monster/schema.json'
27642768
```
27652769

2766-
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.
2770+
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.
27672771

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

@@ -2820,7 +2824,7 @@ a payload like this:
28202824
}
28212825
```
28222826

2823-
will indicate that the `Cat` schema be used. Likewise this schema:
2827+
will indicate that the `#/components/schemas/Cat` schema be used. Likewise this payload:
28242828

28252829
```json
28262830
{
@@ -2829,7 +2833,7 @@ will indicate that the `Cat` schema be used. Likewise this schema:
28292833
}
28302834
```
28312835

2832-
will map to `Dog` because of the definition in the `mapping` element.
2836+
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`.
28332837

28342838

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

0 commit comments

Comments
 (0)