[3.1.0-dev] Improve "Discriminator object" section of the OAS specification

versions/3.1.0.md

@@ -2325,7 +2325,6 @@ 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` field.
 When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model.
-As such, the `discriminator` field MUST be a required field.
 There are two ways to define the value of a discriminator for an inheriting instance.
 - Use the schema name.
 - Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.
@@ -2676,7 +2675,14 @@ components:
 
 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 is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it.
 
-When using the discriminator, _inline_ schemas will not be considered.
+The discriminator object is legal only when using a schema that has one or more of the composite keywords `oneOf`, `anyOf`, `allOf`. Both _inline_ and references can be used as composite child schemas.
+When a child schema is a reference, the discriminator property _MUST_ be present in the payload.
+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.
+Even when the discriminator is used as shortcut hint, the payload MUST still be validated against the JSON schema.
+When a child schema is specified _inline_, the discriminator property is not required to be present in the payload. Validation is applied to determine if the payload matches the child JSON schema.
+
+The discriminator `propertyName` field MUST be a required field in the schema object. However, as shown below, the discriminator is not required to be present in the payload for _inline_ schemas.
+
 
 ##### Fixed Fields
 Field Name | Type | Description
@@ -2686,32 +2692,34 @@ Field Name | Type | Description
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
-The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`.
+##### Discriminator Object Example
 
-In OAS 3.0, a response payload MAY be described to be exactly one of any number of types:
+A payload MAY be described to be exactly one of any number of types:
 
 ```yaml
-MyResponseType:
+MyType:
   oneOf:
+  - type: 'null'
   - $ref: '#/components/schemas/Cat'
   - $ref: '#/components/schemas/Dog'
   - $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`. We can then describe exactly which field tells us which schema to use:
 
 
 ```yaml
-MyResponseType:
+MyType:
   oneOf:
+  - type: 'null'
   - $ref: '#/components/schemas/Cat'
   - $ref: '#/components/schemas/Dog'
   - $ref: '#/components/schemas/Lizard'
   discriminator:
     propertyName: petType
 ```
 
-The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document.  Thus the response payload:
+The expectation now is that a property with name `petType` _MUST_ be present in the payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the payload:
 
 ```json
 {
@@ -2725,7 +2733,7 @@ Will indicate that the `Cat` schema be used in conjunction with 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:
 
 ```yaml
-MyResponseType:
+MyType:
   oneOf:
   - $ref: '#/components/schemas/Cat'
   - $ref: '#/components/schemas/Dog'