Skip to content

Commit 792efcc

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 9709537 commit 792efcc

File tree

1 file changed

+65
-0
lines changed

1 file changed

+65
-0
lines changed

src/oas.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3251,6 +3251,21 @@ The `namespace` field is intended to match the syntax of [XML namespaces](https:
32513251
* Versions 3.1.0, 3.0.3, and earlier of this specification erroneously used the term "absolute URI" instead of "non-relative URI" ("non-relative IRI" as of OAS v3.2.0), so authors using namespaces that include a fragment should check tooling support carefully.
32523252
* XML allows but discourages relative IRI-references, while this specification outright forbids them.
32533253

3254+
##### Handling `null` Values
3255+
3256+
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.
3257+
3258+
However, implementations SHOULD handle `null` values as follows:
3259+
3260+
* For elements, produce an empty element with an `xsi:nil="true"` attribute.
3261+
* For attributes, omit the attribute.
3262+
3263+
Note that for attributes, this makes either a `null` value or a missing property serialize to an omitted attribute.
3264+
As the Schema Object validates the in-memory representation, this allows handling the combination of `null` and a required property.
3265+
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`.
3266+
3267+
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"`).
3268+
32543269
##### XML Object Examples
32553270

32563271
The Schema Objects are followed by an example XML representation produced for the schema shown.
@@ -3671,6 +3686,56 @@ The in-memory instance data structure for the above example would be:
36713686
]
36723687
```
36733688

3689+
###### XML With `null` Values
3690+
3691+
Recall that the schema validates the in-memory data, not the XML document itself.
3692+
The properties of the `"metadata"` element are omitted for brevity as it is here to show how the `null` value is represented.
3693+
3694+
```yaml
3695+
product:
3696+
type: object
3697+
required:
3698+
- count
3699+
- description
3700+
- related
3701+
properties:
3702+
count:
3703+
type:
3704+
- number
3705+
- "null"
3706+
xml:
3707+
nodeType: attribute
3708+
rating:
3709+
type: string
3710+
xml:
3711+
nodeType: attribute
3712+
description:
3713+
type: string
3714+
related:
3715+
type:
3716+
- object
3717+
- "null"
3718+
```
3719+
3720+
```xml
3721+
<product>
3722+
<description>Thing</description>
3723+
<related xsi:nil="true" />
3724+
</product>
3725+
```
3726+
3727+
The above XML example corresponds to the following in-memory instance:
3728+
3729+
```json
3730+
{
3731+
"product": {
3732+
"count": null,
3733+
"description": "Thing",
3734+
"related": null
3735+
}
3736+
}
3737+
```
3738+
36743739
#### Security Scheme Object
36753740

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

0 commit comments

Comments
 (0)