Align 3.1.1 with 3.0.4 #3953
Align 3.1.1 with 3.0.4 #3953
Conversation
versions/3.1.1.md
Outdated
| <!-- 3.0.4 contains the following text: does it also apply to 3.1.1? | ||
| As such, the `discriminator` field MUST be a required field. | ||
| There are two ways to define the value of a discriminator for an inheriting instance. | ||
| - Use the schema name. | ||
| - Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. | ||
| As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. | ||
| --> |
There was a problem hiding this comment.
Does this 3.0.4 text also apply to 3.1.1?
There was a problem hiding this comment.
@ralfhandl this is separate from the changes I made - I don't think I ever touched this section (which is the section that #3951 is about). I can't recall the details of this MUST, but in #708 we apparently decided that the field would continue to be required.
Ideally, we would change this part in both versions, replacing "given id" with "component name" or "name within the Components Object":
As such, inline schema definitions, which do not have a given id, cannot be used in polymorphism.
This is confusing, because the "id" here is the name under the Components Object, not the $id keyword (which is supported in 3.1). I think I also avoided the phrase "inline schemas" when I did the other edits but can't remember right now- I'm less concerned about that.
There was a problem hiding this comment.
This text is present in 3.1.0 and apparently got lost during the refactoring, adding it back now.
The last sentence is not only confusing, it is also wrong as one can use $ref pointing to an "inline schema" anywhere in the OpenAPI document.
Adjusted the text accordingly and will "backport" this to 3.0.4 once we agree.
versions/3.1.1.md
Outdated
| @@ -2790,8 +2788,15 @@ The OpenAPI Specification allows combining and extending model definitions using | |||
| `allOf` takes an array of object definitions that are validated *independently* but together compose a single object. | |||
|
|
|||
| While composition offers model extensibility, it does not imply a hierarchy between the models. | |||
| To support polymorphism, the OpenAPI Specification adds the `discriminator` keyword. | |||
| To support polymorphism, the OpenAPI Specification adds the `discriminator` field. | |||
There was a problem hiding this comment.
I cross-checked our predominant use of "keyword" and "field":
- "keyword" if it is defined by JSON Schema
- "field" if it is defined by OAS in one of the "Fixed Fields" sections
|
@handrews to check discriminator concern. |
@lornajane Question resolved, please review |
Editorial changes taken over from 3.0.4.
Additional changes here are to be synced back to 3.0.4 via #3966