Skip to content

Clarify discriminator non-impact on validation #3907

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 1 commit into from
Jun 17, 2024
Merged

Clarify discriminator non-impact on validation #3907

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 7 additions & 0 deletions versions/3.0.4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3026,6 +3026,8 @@ When request bodies or response payloads may be one of a number of different sch
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.

Note that `discriminator` MUST NOT change the validation outcome of the schema.

##### Fixed Fields
Field Name | Type | Description
---|:---:|---
Expand All @@ -3034,11 +3036,16 @@ Field Name | Type | Description

##### Conditions for Using the Discriminator Object
The Discriminator Object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`.

In both the `oneOf` and `anyOf` use cases, where those keywords are adjacent to `discriminator`, all possible schemas MUST be listed explicitly.

To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas building on the parent schema via an `allOf` construct may be used as an alternate schema.
It is implementation-defined as to whether all named [Schema Objects](#schemaObject) under the [Components Object](#componentsObject), or only those that are otherwise directly referenced are searched for `allOf` references to the parent schema.
However, it is RECOMMENDED to search all named schemas in the Components Object because it is common with the `allOf` usage for other parts of the API to only directly reference the parent schema.

The `allOf` form of `discriminator` is _only_ useful for non-validation use cases; validation with the parent schema with this form of `discriminator` _does not_ perform a search for child schemas or use them in validation in any way.
This is because `discriminator` cannot change the validation outcome, and no standard JSON Schema keyword connects the parent schema to the child schemas.

The behavior of any configuration of `oneOf`, `anyOf`, `allOf` and `discriminator` that is not described above is undefined.

##### Options for Mapping Values to Schemas
Expand Down