Apply suggestions from code review

Co-authored-by: Adam Altman <[email protected]>

Author: jdesrosiers

versions/3.1.1.md

@@ -2346,7 +2346,7 @@ The OpenAPI Specification allows combining and extending model definitions using
 
 While composition offers model extensibility, it does not imply a hierarchy between the models.
 To support polymorphism, the OpenAPI Specification adds the `discriminator` keyword.
-When used, the `discriminator` will indicate the name of the property that hints which schema definition is expected to validate the structure of the model.
+When used, the `discriminator` indicates the name of the property that hints which schema definition is expected to validate the structure of the model.
 
 ###### XML Modeling
 
@@ -2693,7 +2693,7 @@ components:
 
 #### <a name="discriminatorObject"></a>Discriminator Object
 
-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` keyword is used to inform the consumer of the document which of the alternatives is expected or preferred.
+When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object gives a hint about the expected schema of the document. It can be used to aid in serialization, deserialization, and validation.
 
 `discriminator` uses a schema's "name" to automatically map a property value to
 a schema. The schema's "name" is the property name used when declaring the
@@ -2726,7 +2726,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`. Evaluating a `oneOf` can be a costly operation, so `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` keyword cannot change the validation result of the `oneOf`, it can only 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:
+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 as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` keyword cannot change the validation result of the `oneOf`, it can only help make the evaluation more efficient and provide better error messaging. We can specify the exact field that tells us which schema is expected to match the instance:
 
 ```yaml
 MyResponseType:
@@ -2747,7 +2747,7 @@ The expectation now is that a property with name `petType` _MUST_ be present in
 }
 ```
 
-Will indicate that the `Cat` schema is the alternative that is expected to match this payload.
+Will indicate that the `Cat` schema 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: