documented the discriminator property

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.