Discriminator: Can't be a hint and a shortcut

The `discriminator` keyword can't be a hint and a shortcut. I tried here
to modify any language that might suggest that `discriminator` overrides
the behavior of `anyOf`/`oneOf` in any way.

Author: jdesrosiers

versions/3.1.1.md

@@ -2727,8 +2727,7 @@ MyResponseType:
   - $ref: '#/components/schemas/Lizard'
 ```
 
-which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`.  In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use:
-
+which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Evaluating a `oneOf` can be a costly operation, so discriminator MAY be used to act as a "hint" to improve the efficiency of validation and selection of the matching schema. The `discriminator` keyword can not change the validation result of the `oneOf`, it can only be help make the evaluation more efficient and provide better error messaging. We can then describe exactly which field tells us which schema is expected to match the instance:
 
 ```yaml
 MyResponseType:
@@ -2749,7 +2748,7 @@ The expectation now is that a property with name `petType` _MUST_ be present in
 }
 ```
 
-Will indicate that the `Cat` schema be used in conjunction with this payload.
+Will indicate that the `Cat` schema is the alternative that is expected to match this payload.
 
 In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used:
 
@@ -2769,7 +2768,7 @@ MyResponseType:
 
 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.
 
-When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload.
+When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity for serializers/deserializers where multiple schemas may satisfy a single payload.
 
 In both the `oneOf` and `anyOf` use cases, all possible schemas MUST be listed explicitly.  To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an `allOf` construct may be used as an alternate schema.
 
@@ -2824,7 +2823,7 @@ a payload like this:
 }
 ```
 
-will indicate that the `#/components/schemas/Cat` schema be used.  Likewise this payload:
+will indicate that the `#/components/schemas/Cat` schema is expected to match.  Likewise this payload:
 
 ```json
 {