v3.1.2: Root XML element name comes from component name #4576
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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).
handrews
added
xml
clarification
ralfhandl
requested changes
May 15, 2025
| @@ -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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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).