v3.2: Support all common XML node types (element, attribute, text, cdata) #4592
Conversation
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.
This change adds a nodeType field to support the four most commonly used XML node types: element, attribute, text, and cdata. A fifth nodetype, none, is used to prevent a Schema Object from producing a node. This also removes the restriction on where the xml field and XML Object can appear, as the nodeType system is more flexible than the old system. This deprecates two existing fields: * attribute, replaced by nodeType: attribute * wrapped, replaced by nodeType: none
handrews
added
enhancement
xml
media and encoding
|
|
||
| ##### Fixed Fields | ||
|
|
||
| | 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-node-type"></a>nodeType | `string` | One of `element`, `attribute`, `text`, `cdata`, or `none`, as explained under [XML Node Types](#xml-node-types). The default value is `none` if `$ref`, `$dynamicRef`, or `type: "array"` is present in the [Schema Object](#schema-object) containing the XML Object, and `element` otherwise. | |
There was a problem hiding this comment.
I'm not 100% the bits about $ref and $dynamicRef are backwards-compatible, because I'm not sure what, if anything, the behavior was in those cases before, as "property schema" was not well-defined. If we mean "literal inline schema directly under a name under properties without references", then there was no defined behavior and we can do what we want.
Otherwise, it might not be, and we should let schemas containing $ref or $dynamicRef have a default nodeType of element, and folks can explicitly set them to none. I don't think that change would impact anything else in this PR, and might be the more conservative compatibility choice.
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
There really isn't a native `null` type in XML, as both elements and attributes that are empty have an empty string value. We also need to leave the behavior implementation-defined for compatibility. However, the `xsi:nil` attribute is the closest thing to a `null` element. Attributes are harder, and the best I can come up with is letting `null` behave the same as an omitted attribute for the purpose of serialization.
The guidance is the same as for serializing `null` and other non-text data types to text in other text-based media types such as the form media types.
|
Now with I decided that outright forbidding |
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
nullvalues)This change removes the restriction on where the
xmlfield and XML Object can appear, and adds anodeTypefield to support the four most commonly used XML node types:element,attribute,text, andcdata. A fifth nodetype,none, is used to prevent a Schema Object from producing a node.It also adds many examples of how to model different XML scenarios, including using
prefixItemsfor complex ordered nodes.While this could have been made much simpler by always defaulting
nodeTypetoelement, a more complex requirement was needed to preserve compatibility with the existing (but now deprecated - see also PR #4591)attributeandwrappedfields. This way, the behavior of an XML object that is empty or uses onlyname,prefix, and/ornamespacebehaves the same whether you look at defaults fornodeTypeor forattributeandwrapped.Finally, this PR ports the guidance on handling
nullattributes and elements to 3.2.I expect the deprecation of
attributeandwrappedto be controversial, but there are several reasons for doing it:text, to indicate text nodes. But if we are going to support text nodes, we definitely also want to support CDATA sections, which would require three fields (attribute,text, andcdata) that were all mutually exclusive. One boolean is fine, but three to manage a single state is more design smell than I can handle.wrappedfield is a very specific case of a more general problem, which is Schema Objects that do not correspond to XML nodes. The old wording only acknowledged "property" and "root" schemas, and ignored the many other sorts of Schema Objects that might appear, and the complex ways in which they might map (or not) to XML nodes. ThenodeType: noneconstruct allows controlling this in a generalized way.namebehavior, as certain types have names and others do not. This is much more intuitive than logic involvingwrapped.null-handling problems in Formalize how to express null value in xml #3959 are tricky, and this allows us to (if we want) define clear behavior fornodeType: attributewithout breaking existing support forattribute: true. [NOTE: I ended up not trying to put restrictions onnullandnodeType: attributebecause there isn't really any good option but "don't usenullwith this" and forbidding that rather than just discouraging it seems problematic.]I came up with several other possible caveats to call out or clarify, but I wanted to keep this as minimal as possible. If the related concerns come up in review I can add them, otherwise I will do it as a follow-on if it seems useful. But let's see how this lands first.