v3.1.2: Root XML element name comes from component name #4576
Conversation
handrews
added
xml
clarification
src/oas.md
Outdated
| @@ -3447,7 +3447,7 @@ See examples for expected behavior. | |||
|
|
|||
| | Field Name | Type | Description | | |||
| | ---- | :----: | ---- | | |||
| | <a name="xml-name"></a>name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `"array"` (outside the `items`), it will affect the wrapping element if and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. | | |||
| | <a name="xml-name"></a>name | `string` | Replaces the name of the element/attribute used for the described schema property. For the root XML element, the name comes from the [schema component](#components-schemas) name; for other elements or attributes, the name comes from the property name. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `"array"` (outside the `items`), it will affect the wrapping element if and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. | | |||
There was a problem hiding this comment.
Some implementations allow the xml fixed field in any Schema Object, including the Schema Object for the root XML element, and use its name value for the XML element name. If absent, the name of the XML element (or attribute) is the name of the name/value pair whose value is the Schema Object.
Which is straight-forward and what I would have expected, without the funny restriction to "property schemas", a term that is nowhere defined.
I'd not reinforce the surprising restriction to "property schemas" further, or at least add that implementations MAY allow it in any Schema Object, including the one for the XML root element.
There was a problem hiding this comment.
When we port this to 3.2 I was planning on removing the "property schemas" restriction, as I assumed the xml field in a "root schema" should behave exactly as you say.
I'm not sure how to incorporate that here in 3.1.2, though. If @OAI/tsc is OK with relaxing that (as a MAY) in a patch release, I'm happy to do so.
For now, let me try to reword this short of adding that MAY (we can add the MAY in a later PR if we can't sort that out immediately- I'd love to see it, TBH).
Clarifies that the name of the root XML element comes from the component name, which was shown in an example but was unclear due to the use of the obsolete OAS 2.0 terminology "model." This does not change the restriction (in the `xml` field of the Schema Object) that the `xml` field only applies to property schemas (and not root schemas).
This avoids reinforcing the "root schema" vs "property schema" restriction that we plan to relax.
|
@ralfhandl I did an unchanged force-push to rebase, followed by a new commit with new language. Let me know if this is better, I'm happy to try again if this doesn't work either. |
|
Nice! |
Fixes #1435 (as much as can be in a patch release)
Clarifies that the name of the root XML element comes from the component name, which was shown in an example but was unclear due to the use of the obsolete OAS 2.0 terminology "model."
This does not change the restriction (in the
xmlfield of the Schema Object) that thexmlfield only applies to property schemas (and not root schemas).