You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
Copy file name to clipboardExpand all lines: src/oas.md
+65Lines changed: 65 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -3251,6 +3251,21 @@ The `namespace` field is intended to match the syntax of [XML namespaces](https:
3251
3251
* 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.
3252
3252
* XML allows but discourages relative IRI-references, while this specification outright forbids them.
3253
3253
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
+
3254
3269
##### XML Object Examples
3255
3270
3256
3271
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:
3671
3686
]
3672
3687
```
3673
3688
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
+
3674
3739
#### Security Scheme Object
3675
3740
3676
3741
Defines a security scheme that can be used by the operations.
0 commit comments