updated per feedback
MODIFY
versions/3.0.md
versions/3.0.md
@@ -2663,7 +2663,7 @@ Other than the JSON Schema subset fields, the following fields MAY be used for f
Field Name | Type | Description
---|:---:|---
<a name="schemaNullable"></a>nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.
-<a name="schemaDiscriminator"></a>discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#schemaComposition) for more details.
+<a name="schemaDiscriminator"></a>discriminator | [Discriminator Object](#discriminatorObject) | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#schemaComposition) for more details.
<a name="schemaReadOnly"></a>readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`.
<a name="schemaWriteOnly"></a>writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". This means that it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`.
<a name="schemaXml"></a>xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property.
@@ -2826,6 +2826,7 @@ example:
```json
{
+ "components": {
"schemas": {
"ErrorModel": {
"type": "object",
@@ -2864,9 +2865,11 @@ example:
}
}
}
+}
```
```yaml
+components:
schemas:
ErrorModel:
type: object
@@ -2895,6 +2898,7 @@ schemas:
```json
{
+ "components": {
"schemas": {
"Pet": {
"type": "object",
@@ -2964,13 +2968,16 @@ schemas:
}
}
}
+}
```
```yaml
+components:
schemas:
Pet:
type: object
- discriminator: petType
+ discriminator:
+ propertyName: petType
properties:
name:
type: string
@@ -3034,7 +3041,7 @@ MyResponseType:
- $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:
+which means the paylod _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:
```
@@ -3044,7 +3051,7 @@ MyResponseType:
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Lizard'
discriminator:
- property: pet_type
+ propertyName: 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:
@@ -3058,7 +3065,7 @@ The expectation now is that a property with name `pet_type` _must_ be present in
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:
+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:
```
MyResponseType:
@@ -3066,12 +3073,16 @@ MyResponseType:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Lizard'
+ - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json'
discriminator:
property: pet_type
mapping:
- cat: '#/components/schemas/Cat'
+ dog: '#/components/schemas/Dog'
+ monster: 'https://gigantic-server.com/schemas/Monster/schema.json'
```
+Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match a implicit or explicit mapping, no schema can be determined and validation should fail.
+
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.
@@ -3108,6 +3119,14 @@ components:
properties:
bark:
type: string
+ Lizard:
+ allOf:
+ - $ref: '#/components/schemas/Pet'
+ - type: object
+ # all other properties specific to a `Lizard`
+ properties:
+ lovesRocks:
+ type: boolean
```
a payload like this:

updated per feedback