comments per TDC
MODIFY
versions/3.0.md
versions/3.0.md
@@ -2995,7 +2995,6 @@ components:
huntingSkill:
type: string
description: The measured skill for hunting
- default: lazy
enum:
- clueless
- lazy
@@ -3041,7 +3040,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 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 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:
```
@@ -3054,7 +3053,7 @@ MyResponseType:
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:
+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:
```
{
@@ -3075,13 +3074,13 @@ MyResponseType:
- $ref: '#/components/schemas/Lizard'
- $ref: 'https://gigantic-server.com/schemas/Monster/schema.json'
discriminator:
- property: pet_type
+ propertyName: pet_type
mapping:
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.
+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. Note, mapping keys MUST be string values, but tooling may response values to strings for comparison.
When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload.

comments per TDC