documented the discriminator property #1093
Conversation
versions/3.0.md
Outdated
| discriminator: | ||
| property: pet_type | ||
| mapping: | ||
| cat: '#/components/schemas/Cat' |
There was a problem hiding this comment.
Should this be
cachorro: '#/components/schemas/Dog'
(introducing cat is confusing since the above example used "pet_type": "Cat")
There was a problem hiding this comment.
@DavidBiesack you are correct, I will update the example.
versions/3.0.md
Outdated
| - pet_type | ||
| properties: | ||
| pet_type: | ||
| type: string |
There was a problem hiding this comment.
Consider adding an enum for this as well, to allow for validation:
pet_type:
type: string
enum:
- Cat
- cachorro
There was a problem hiding this comment.
That would defeat the goal of this example--here, we're showing that the parent object Pet does not have knowledge of all of the composed types. Thus, any object which extends Pet with the allOf construct is a candidate for use
versions/3.0.md
Outdated
| bark: | ||
| type: string | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Consider adding Lizard: here to be consistent with the previous example.
There was a problem hiding this comment.
sure, I think Lizards are cool
| For example: | ||
|
|
||
| ``` | ||
| components: |
There was a problem hiding this comment.
remove components: and schemas: here since they are not used in the other examples.
There was a problem hiding this comment.
Actually I believe the components/schemas is important here, since we're showing references inside the example. I'll ensure the composition examples are consistent.
|
|
||
| will map to `Dog` because of the definition in the `mappings` element. | ||
|
|
||
|
|
There was a problem hiding this comment.
I suggest also adding a note:
Some OpenAPI definitions use external, reusable schema references such as
properties:
pet_type:
type: string
enum:
- cat
- cachorro
- lizard
oneOf:
- $ref: 'http://www.example.com/schemas/Cat/schema.json'
- $ref: 'http://www.example.com/schemas/Doc/schema.json'
- $ref: 'http://www.example.com/schemas/Lizard/schema.json'
discriminator:
propertyName: pet_type
mapping:
cat: 'http://www.example.com/schemas/Cat/schema.json'
cachorro: 'http://www.example.com/schemas/Doc/schema.json'
lizard: 'http://www.example.com/schemas/Lizard/schema.json'
and an implicit name mapping based on schema names is not possible.
For such cases, a mapping is required.
The above $ref values are JSON Schema files, not OpenAPI documents. Schema may
also be referenced from schema definitions from an external OpenAPI definition:
properties:
pet_type:
type: string
enum:
- cat
- cachorro
- lizard
oneOf:
- $ref: 'http://www.example.com/library.json#/components/schema/Cat.json'
- $ref: 'http://www.example.com/library.json#/components/schema/Doc.json'
- $ref: 'http://www.example.com/library.json#/components/schema/Lizard.json'
discriminator:
propertyName: pet_type
mapping:
cat: $ref: 'http://www.example.com/library.json#/components/schema/Cat.json'
cachorro: $ref: 'http://www.example.com/library.json#/components/schema/Doc.json'
lizard: $ref: 'http://www.example.com/library.json#/components/schema/Lizard.json'
[in particular, citing external JSON Schema, and not just #/definitions/SchemaName from other OpenAPI 2.0 documents, worked in 2.0 and we need to ensure this still works in 3.0, whether this involves discriminators or not.]
There was a problem hiding this comment.
good point, I'll add language around this 👍
| ##### 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. |
There was a problem hiding this comment.
The examples are using property, here it is propertyName.
versions/3.0.md
Outdated
| - $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: |
There was a problem hiding this comment.
Are we sure "bypass validation" is the right phrase here?
There was a problem hiding this comment.
yes, I'll rephrase. will ==> may, bypass ==> shortcut
versions/3.0.md
Outdated
|
|
||
| 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: |
There was a problem hiding this comment.
What happens if the discriminator value does not match a schema or mapping? We should probably document this as it will impact tooling.
|
@OAI/tdc updated per feedback above. Thanks! |
|
@OAI/tdc please review and approve--changes from call have been merged. |
| - packSize | ||
| ``` | ||
|
|
||
| #### <a name="discriminatorObject"></a>Discriminator Object |
There was a problem hiding this comment.
I suggest renaming this anchor as discriminatorProperty / Discriminator Property so that OAS only uses "Object" when referring to a JSON object.
There was a problem hiding this comment.
The discriminator object described here actually is a JSON (or YAML) object in the API definition (In OpenAPI 2.0 it was a simple string), though it describes a single (string) property of the JSON payload.
I would say the name is fine.
There was a problem hiding this comment.
@DavidBiesack you are correct. Using title is a bad idea, and I've disallowed inline schemas for consideration with the discriminator.
|
#TDC: Merge it! |
Fixes #1085