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
@@ -2696,7 +2696,11 @@ components:
2696
2696
2697
2697
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.
2698
2698
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".
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.
2762
2766
2763
2767
When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload.
2764
2768
@@ -2815,7 +2819,7 @@ a payload like this:
2815
2819
}
2816
2820
```
2817
2821
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:
2819
2823
2820
2824
```json
2821
2825
{
@@ -2824,7 +2828,7 @@ will indicate that the `Cat` schema be used. Likewise this schema:
2824
2828
}
2825
2829
```
2826
2830
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`.
0 commit comments