Skip to content

Commit 8f03154

Browse files
committed
Provide guidance on null in XML.
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.
1 parent 80f5126 commit 8f03154

File tree

1 file changed

+96
-0
lines changed

1 file changed

+96
-0
lines changed

src/oas.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3455,12 +3455,29 @@ See examples for expected behavior.
34553455

34563456
This object MAY be extended with [Specification Extensions](#specification-extensions).
34573457

3458+
##### Namespace Limitations
3459+
34583460
The `namespace` field is intended to match the syntax of [XML namespaces](https://www.w3.org/TR/xml-names11/), although there are a few caveats:
34593461

34603462
* Versions 3.1.0, 3.0.3, and earlier of this specification erroneously used the term "absolute URI" instead of "non-relative URI", so authors using namespaces that include a fragment should check tooling support carefully.
34613463
* XML allows but discourages relative URI-references, while this specification outright forbids them.
34623464
* XML 1.1 allows IRIs ([RFC3987](https://datatracker.ietf.org/doc/html/rfc3987)) as namespaces, and specifies that namespaces are compared without any encoding or decoding, which means that IRIs encoded to meet this specification's URI syntax requirement cannot be compared to IRIs as-is.
34633465

3466+
##### Handling `null` Values
3467+
3468+
XML does not, by default, have a concept equivalent to `null`, and to preserve compatibility with version 3.1.1 and earlier of this specification, the behavior of serializing `null` values is implementation-defined.
3469+
3470+
However, implementations SHOULD handle `null` values as follows:
3471+
3472+
* For elements, produce an empty element with an `xsi:nil="true"` attribute
3473+
* For attributes, omit the attribute
3474+
3475+
Note that for attributes, this makes either a `null` value or a missing property serialize to an omitted attribute.
3476+
As the Schema Object validates the in-memory representation, this allows handling the combination of `null` and a required property.
3477+
However, because there is no distinct way to represent `null` as an attribute, it is RECOMMENDED to make attribute properties optional rather than use `null`.
3478+
3479+
To ensure correct round-trip behavior, when parsing an element that omits an attribute, implementations SHOULD set the corresponding property to `null` if the schema allows for that value (e.g. `type: ["number", "null"]`), and omit the property otherwise (e.g.`type: "number"`).
3480+
34643481
##### XML Object Examples
34653482

34663483
Each of the following examples represent the value of the `properties` keyword in a [Schema Object](#schema-object) that is omitted for brevity.
@@ -3796,6 +3813,85 @@ animals:
37963813
</aliens>
37973814
```
37983815

3816+
###### XML With `null` Values
3817+
3818+
Recall that the schema validates the in-memory data, not the XML document itself.
3819+
The properties of the `"metadata"` element are omitted for brevity as it is here to show how the `null` value is represented.
3820+
3821+
```json
3822+
{
3823+
"product": {
3824+
"type": "object",
3825+
"required": ["count", "description", "related"],
3826+
"properties": {
3827+
"count": {
3828+
"type": ["number", "null"],
3829+
"xml": {
3830+
"attribute": true
3831+
}
3832+
},
3833+
"rating": {
3834+
"type": "string",
3835+
"xml": {
3836+
"attribute": true
3837+
}
3838+
},
3839+
"description": {
3840+
"type": "string"
3841+
},
3842+
"related": {
3843+
"type": ["object", "null"]
3844+
}
3845+
}
3846+
}
3847+
}
3848+
```
3849+
3850+
```yaml
3851+
product:
3852+
type: object
3853+
required:
3854+
- count
3855+
- description
3856+
- related
3857+
properties:
3858+
count:
3859+
type:
3860+
- number
3861+
- "null"
3862+
xml:
3863+
attribute: true
3864+
rating:
3865+
type: string
3866+
xml:
3867+
attribute: true
3868+
description:
3869+
type: string
3870+
related:
3871+
type:
3872+
- object
3873+
- "null"
3874+
```
3875+
3876+
```xml
3877+
<product>
3878+
<description>Thing</description>
3879+
<related xsi:nil="true" />
3880+
</product>
3881+
```
3882+
3883+
The above XML example corresponds to the following in-memory instance:
3884+
3885+
```json
3886+
{
3887+
"product": {
3888+
"count": null,
3889+
"description": "Thing",
3890+
"related": null
3891+
}
3892+
}
3893+
```
3894+
37993895
#### Security Scheme Object
38003896

38013897
Defines a security scheme that can be used by the operations.

0 commit comments

Comments
 (0)