You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
Copy file name to clipboardExpand all lines: versions/3.1.1.md
+8-4Lines changed: 8 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -2701,7 +2701,11 @@ components:
2701
2701
2702
2702
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.
2703
2703
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".
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.
2767
2771
2768
2772
When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload.
2769
2773
@@ -2820,7 +2824,7 @@ a payload like this:
2820
2824
}
2821
2825
```
2822
2826
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:
2824
2828
2825
2829
```json
2826
2830
{
@@ -2829,7 +2833,7 @@ will indicate that the `Cat` schema be used. Likewise this schema:
2829
2833
}
2830
2834
```
2831
2835
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`.
0 commit comments