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
+96Lines changed: 96 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -3455,12 +3455,29 @@ See examples for expected behavior.
3455
3455
3456
3456
This object MAY be extended with [Specification Extensions](#specification-extensions).
3457
3457
3458
+
##### Namespace Limitations
3459
+
3458
3460
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:
3459
3461
3460
3462
* 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.
3461
3463
* XML allows but discourages relative URI-references, while this specification outright forbids them.
3462
3464
* 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.
3463
3465
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
+
3464
3481
##### XML Object Examples
3465
3482
3466
3483
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:
3796
3813
</aliens>
3797
3814
```
3798
3815
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
+
3799
3895
#### Security Scheme Object
3800
3896
3801
3897
Defines a security scheme that can be used by the operations.
0 commit comments