documented the discriminator property
MODIFY
versions/3.0.md
versions/3.0.md
@@ -3012,6 +3012,125 @@ schemas:
- packSize
```
+#### <a name="discriminatorObject"></a>Discriminator Object
+
+When request bodies or response payloads may be one of a number of different schemas, a `discriminator` property can be used to aid in serialization, deserialization, and validation. The discriminator is a specific property in an object which is used to inform the consumer of the specification of an alternative schema based on the value associated with it.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+<a name="propertyName"></a>propertyName | `string` | **required** the name of the property in the payload that will hold the discriminator value.
+<a name="discriminatorMapping"></a> mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references.
+
+The discriminator attribute is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`.
+
+In OAS 3.0, a response payload may be described to be exactly one of any number of types:
+
+```
+MyResponseType:
+ oneOf:
+ - $ref: '#/components/schemas/Cat'
+ - $ref: '#/components/schemas/Dog'
+ - $ref: '#/components/schemas/Lizard'
+```
+
+which means the paylod _must_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator will act as a "hint" to bypass 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:
+
+
+```
+MyResponseType:
+ oneOf:
+ - $ref: '#/components/schemas/Cat'
+ - $ref: '#/components/schemas/Dog'
+ - $ref: '#/components/schemas/Lizard'
+ discriminator:
+ property: pet_type
+```
+
+The expectation now is that a property with name `pet_type` _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:
+
+```
+{
+ "id": 12345,
+ "pet_type": "Cat"
+}
+```
+
+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, an optional `mapping` definition may be used:
+
+```
+MyResponseType:
+ oneOf:
+ - $ref: '#/components/schemas/Cat'
+ - $ref: '#/components/schemas/Dog'
+ - $ref: '#/components/schemas/Lizard'
+ discriminator:
+ property: pet_type
+ mapping:
+ cat: '#/components/schemas/Cat'
+```
+
+When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity 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 composing the parent schema in an `allOf` construct may be used as an alternate schema.
+
+For example:
+
+```
+components:
+ schemas:
+ Pet:
+ type: object
+ required:
+ - pet_type
+ properties:
+ pet_type:
+ type: string
+ discriminator:
+ propertyName: pet_type
+ mapping:
+ cachorro: Dog
+ Cat:
+ allOf:
+ - $ref: '#/components/schemas/Pet'
+ - type: object
+ # all other properties specific to a `Cat`
+ properties:
+ name:
+ type: string
+ Dog:
+ allOf:
+ - $ref: '#/components/schemas/Pet'
+ - type: object
+ # all other properties specific to a `Dog`
+ properties:
+ bark:
+ type: string
+```
+
+a payload like this:
+
+```
+{
+ "pet_type": "Cat",
+ "name": "misty"
+}
+```
+
+will indicate that the `Cat` schema be used. Likewise this schema:
+
+```
+{
+ "pet_type": "cachorro",
+ "bark": "soft"
+}
+```
+
+will map to `Dog` because of the definition in the `mappings` element.
+
+
#### <a name="xmlObject"></a>XML Object
A metadata object that allows for more fine-tuned XML model definitions.

documented the discriminator property