Merge pull request #3907 from handrews/disc-val-304

Clarify discriminator non-impact on validation

Author: handrews

versions/3.0.4.md

@@ -3062,6 +3062,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
 ---|:---:|---
@@ -3070,11 +3072,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