diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 8dda05e8ba..78c4643e79 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -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 ---|:---:|--- @@ -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