From f125f7e63ffe433d528686669da9087008aa87e8 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Tue, 13 May 2025 10:00:02 -0700 Subject: [PATCH 1/9] Root XML element name comes from component name 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). --- src/oas.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/src/oas.md b/src/oas.md index 9151acac30..8d7be6fc70 100644 --- a/src/oas.md +++ b/src/oas.md @@ -3146,22 +3146,25 @@ animals: ###### XML Attribute, Prefix and Namespace -In this example, a full model definition is shown. +In this example, a full [schema component](#components-schemas) definition is shown. +Note that the name of the root XML element comes from the component name. ```yaml -Person: - type: object - properties: - id: - type: integer - format: int32 - xml: - attribute: true - name: - type: string - xml: - namespace: https://example.com/schema/sample - prefix: sample +components: + schemas: + Person: + type: object + properties: + id: + type: integer + format: int32 + xml: + attribute: true + name: + type: string + xml: + namespace: https://example.com/schema/sample + prefix: sample ``` ```xml From 45e207adc586a615050e7ecf5962512711a7d32d Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 15 May 2025 10:05:50 -0700 Subject: [PATCH 2/9] Align wording with components rather than "root" This avoids reinforcing the "root schema" vs "property schema" restriction that we plan to relax. --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 8d7be6fc70..fe92f17336 100644 --- a/src/oas.md +++ b/src/oas.md @@ -3085,7 +3085,7 @@ See examples for expected behavior. | Field Name | Type | Description | | ---- | :----: | ---- | -| 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. | +| name | `string` | Replaces the inferred name of the element/attribute used for the described schema property. For the root schema object of a [schema component](#components-schemas), the inferred name is the name of the component; for other schemas the name is inferred from the parent property name. 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. | | namespace | `string` | The IRI ([[RFC3987]]) of the namespace definition. Value MUST be in the form of a non-relative IRI. | | prefix | `string` | The prefix to be used for the [name](#xml-name). | | attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. | From 445487ba514a74ba0ec511de3684a457e7b311e6 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 14 May 2025 11:10:40 -0700 Subject: [PATCH 3/9] Support all common XML node types 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 --- src/oas.md | 280 +++++++++++++++++++++++-------- src/schemas/validation/meta.yaml | 17 +- 2 files changed, 227 insertions(+), 70 deletions(-) diff --git a/src/oas.md b/src/oas.md index fe92f17336..4396dd3cc9 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2475,7 +2475,7 @@ JSON Schema implementations MAY choose to treat keywords defined by the OpenAPI | Field Name | Type | Description | | ---- | :----: | ---- | | discriminator | [Discriminator Object](#discriminator-object) | The discriminator provides a "hint" for which of a set of schemas a payload is expected to satisfy. See [Composition and Inheritance](#composition-and-inheritance-polymorphism) for more details. | -| xml | [XML Object](#xml-object) | This MAY be used only on property schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. | +| xml | [XML Object](#xml-object) | Adds additional metadata to describe the XML representation of this schema. | | externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this schema. | | example | Any | A free-form field to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.

**Deprecated:** The `example` field has been deprecated in favor of the JSON Schema `examples` keyword. Use of `example` is discouraged, and later versions of this specification may remove it. | @@ -3077,22 +3077,68 @@ will map to `#/components/schemas/Dog` because the `dog` entry in the `mapping` #### XML Object A metadata object that allows for more fine-tuned XML model definitions. - -When using arrays, XML element names are _not_ inferred (for singular/plural forms) and the `name` field SHOULD be used to add that information. -See examples for expected behavior. +When using a Schema Object with XML, if no XML Object is present, the behavior is determined by the XML Object's default field values. ##### Fixed Fields | Field Name | Type | Description | | ---- | :----: | ---- | -| name | `string` | Replaces the inferred name of the element/attribute used for the described schema property. For the root schema object of a [schema component](#components-schemas), the inferred name is the name of the component; for other schemas the name is inferred from the parent property name. 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. | +| 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. | +| name | `string` | Sets the name of the element/attribute used for the described schema property, replacing name that was inferred as described under [XML Node Names](#xml-node-names). This field SHALL be ignored if the `nodeType` is `text`, `cdata`, or `none`. | | namespace | `string` | The IRI ([[RFC3987]]) of the namespace definition. Value MUST be in the form of a non-relative IRI. | | prefix | `string` | The prefix to be used for the [name](#xml-name). | -| attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. | -| wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `"array"` (outside the `items`). | +| attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. If `nodeType` is present, this field MUST NOT be present.

**Deprecated:** Use `nodeType: attribute` in place of `attribute: true` | +| wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `"array"` (outside the `items`). If `nodeType` is present, this field MUST NOT be present.

**Deprecated:** Set `nodeType: element` explicitly in place of `wrapped: true` | + +Note that when generating an XML document from object data, the order of the nodes is undefined. +Use `prefixItems` to control node ordering. + +See [Appendix B](#appendix-b-data-type-conversion) for a discussion of converting values of various types to string representations. This object MAY be extended with [Specification Extensions](#specification-extensions). +##### XML Node Types + +Each Schema Object describes a particular type of XML [node](https://dom.spec.whatwg.org/#interface-node) which is specified by the `nodeType` field, which has the following possible values. +Except for the special value `none`, these values have numeric equivalents in the DOM [specification](https://dom.spec.whatwg.org/#interface-node) which are given in parentheses after the name: + +* `element` (1): The schema represents an element and describes its contents +* `attribute` (2): The schema represents an attribute and describes its value +* `text` (3): The schema represents a text node (parsed character data) +* `cdata` (4): The schema represents a CDATA section +* `none`: The schema does not correspond to any node in the XML document, and its contents are included directly under the parent schema's node + +The `none` type is useful for JSON Schema constructs that require more Schema Objects than XML nodes, such as a schema containing only `$ref` that exists to facilitate re-use rather than imply any structure. + +###### Modeling Element Lists + +For historical compatibility, schemas of `type: array` default to `nodeType: none`, placing the nodes for each array item directly under the parent node. +This also aligns with the inferred naming behavior defined under [XML Node Names](#xml-node-names). + +To produce an element wrapping the list, set an explicit `nodeType: element` on the `type: array` schema. +When doing so, it is advisable to set an explicit name on either the wrapping element or the item elements to avoid them having the same inferred name. +See examples for expected behavior. + +###### Implicit and Explicit `text` Nodes + +If an `element` node has a primitive type, then the schema also produces an implicit `text` node described by the schema for the contents of the `element` node named by the property name (or `name` field). + +Explicit `text` nodes are necessary if an element has both attributes and content. + +Note that placing two `text` nodes adjacent to each other is ambiguous for parsing, and the resulting behavior is implementation-defined. + +##### XML Node Names + +The `element` and `attribute` node types require a name, which MUST be inferred from the schema as follows, unless overridden by the `name` field: + +* For schemas directly under the [Components Object's](#components-object) `schemas` field, the component name is the inferred name. +* For property schemas, and for array item schemas under a property schema, the property name is the inferred name +* In all other cases, such as an inline schema under a [Media Type Object's](#media-type-object) `schema` field, no name can be inferred and an XML Object with a `name` field MUST be present + +Note that when using arrays, singular vs plural forms are _not_ inferred, and must be set explicitly. + +##### Namespace Limitations + 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: * 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. @@ -3100,29 +3146,31 @@ The `namespace` field is intended to match the syntax of [XML namespaces](https: ##### XML Object Examples -Each of the following examples represent the value of the `properties` keyword in a [Schema Object](#schema-object) that is omitted for brevity. -The JSON and YAML representations of the `properties` value are followed by an example XML representation produced for the single property shown. +The Schema Objects are followed by an example XML representation produced for the schema shown. +For examples using `attribute` or `wrapped`, please see version 3.1 of the OpenAPI Specification. -###### No XML Element +###### No XML Object -Basic string property: +Basic string property (`nodeType` is `element` by default): ```yaml -animals: - type: string +properties: + animals: + type: string ``` ```xml ... ``` -Basic string array property ([`wrapped`](#xml-wrapped) is `false` by default): +Basic string array property (`nodeType` is `none` by default): ```yaml -animals: - type: array - items: - type: string +properties: + animals: + type: array + items: + type: string ``` ```xml @@ -3134,10 +3182,11 @@ animals: ###### XML Name Replacement ```yaml -animals: - type: string - xml: - name: animal +properties: + animals: + type: string + xml: + name: animal ``` ```xml @@ -3146,7 +3195,6 @@ animals: ###### XML Attribute, Prefix and Namespace -In this example, a full [schema component](#components-schemas) definition is shown. Note that the name of the root XML element comes from the component name. ```yaml @@ -3178,12 +3226,13 @@ components: Changing the element names: ```yaml -animals: - type: array - items: - type: string - xml: - name: animal +properties: + animals: + type: array + items: + type: string + xml: + name: animal ``` ```xml @@ -3191,17 +3240,18 @@ animals: value ``` -The external `name` field has no effect on the XML: +The `name` field for the `type: array` schema has no effect because the default `nodeType` for that object is `none`: ```yaml -animals: - type: array - items: - type: string +properties: + animals: + type: array + items: + type: string + xml: + name: animal xml: - name: animal - xml: - name: aliens + name: aliens ``` ```xml @@ -3209,15 +3259,16 @@ animals: value ``` -Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally: +Even when a wrapping element is explicitly created by setting `nodeType` to `element`, if a name is not explicitly defined, the same name will be used for both the wrapping element and the list item elements: ```yaml -animals: - type: array - items: - type: string - xml: - wrapped: true +properties: + animals: + type: array + items: + type: string + xml: + nodeType: element ``` ```xml @@ -3230,14 +3281,15 @@ animals: To overcome the naming problem in the example above, the following definition can be used: ```yaml -animals: - type: array - items: - type: string +properties: + animals: + type: array + items: + type: string + xml: + name: animal xml: - name: animal - xml: - wrapped: true + nodeType: element ``` ```xml @@ -3247,18 +3299,19 @@ animals: ``` -Affecting both internal and external names: +Affecting both wrapping element and item element names: ```yaml -animals: - type: array - items: - type: string +properties: + animals: + type: array + items: + type: string + xml: + name: animal xml: - name: animal - xml: - name: aliens - wrapped: true + name: aliens + nodeType: element ``` ```xml @@ -3268,16 +3321,17 @@ animals: ``` -If we change the external element but not the internal ones: +If we change the wrapping element name but not the item element names: ```yaml -animals: - type: array - items: - type: string - xml: - name: aliens - wrapped: true +properties: + animals: + type: array + items: + type: string + xml: + name: aliens + nodeType: element ``` ```xml @@ -3287,6 +3341,96 @@ animals: ``` +###### Elements With Attributes And Text + +```yaml +properties: + animals: + type: array + xml: + nodeType: element + name: animals + items: + properties: + kind: + type: string + xml: + nodeType: attribute + name: animal + content: + type: string + xml: + nodeType: text +``` + +```xml + + Fluffy + Fido + +``` + +###### Referenced Element With CDATA + +In this example, no element is created for the Schema Object that contains only the `$ref`, as its `nodeType` defaults to `none`. +It is necessary to create a subschema for the CDATA section as otherwise the content would be treated as an implicit node of type `text`. + +```yaml +paths: + /docs: + get: + responses: + "200": + content: + application/xml: + $ref: "#/components/schemas/Documentation" +components: + schemas: + Documentation: + type: object + properties: + content: + type: string + contentMediaType: text/html + xml: + nodeType: cdata +``` + +```xml + + Awesome Docs]]> + +``` + +###### Element With Text Before and After a Child Element + +In this example, `prefixItems` is used to control the ordering. +Since `prefixItems` works with arrays, we need to explicitly set the `nodeType` to `element`. +Within `prefixItems`, we need to explicitly set the `nodeType` of the `text` nodes, but do not need a name, while the data node's default `nodeType` of `element` is correct, but it needs an explicit `name`: + +```yaml +components: + schemas: + Report: + type: array + xml: + nodeType: element + prefixItems: + - type: string + xml: + nodeType: text + - type: number + xml: + name: data + - type: string + xml: + nodeType: text +``` + +```xml +Some preamble text.42Some postamble text. +``` + #### Security Scheme Object Defines a security scheme that can be used by the operations. diff --git a/src/schemas/validation/meta.yaml b/src/schemas/validation/meta.yaml index 491190a221..52f5ea2ed0 100644 --- a/src/schemas/validation/meta.yaml +++ b/src/schemas/validation/meta.yaml @@ -55,8 +55,14 @@ $defs: xml: $ref: '#/$defs/extensible' properties: - attribute: - type: boolean + nodeType: + type: string + enum: + - element + - attribute + - text + - cdata + - none name: type: string namespace: @@ -64,7 +70,14 @@ $defs: type: string prefix: type: string + attribute: + type: boolean wrapped: type: boolean type: object + dependentSchemas: + nodeType: + properties: + attribute: false + wrapped: false unevaluatedProperties: false From 257680135c2eb47d9cd4cbb6390efca8deaf2303 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 15 May 2025 19:39:07 -0700 Subject: [PATCH 4/9] Better wording and formatting --- src/oas.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/oas.md b/src/oas.md index 4396dd3cc9..ffbf6722c5 100644 --- a/src/oas.md +++ b/src/oas.md @@ -3084,11 +3084,11 @@ When using a Schema Object with XML, if no XML Object is present, the behavior i | Field Name | Type | Description | | ---- | :----: | ---- | | 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. | -| name | `string` | Sets the name of the element/attribute used for the described schema property, replacing name that was inferred as described under [XML Node Names](#xml-node-names). This field SHALL be ignored if the `nodeType` is `text`, `cdata`, or `none`. | +| name | `string` | Sets the name of the element/attribute corresponding to the schema, replacing name that was inferred as described under [XML Node Names](#xml-node-names). This field SHALL be ignored if the `nodeType` is `text`, `cdata`, or `none`. | | namespace | `string` | The IRI ([[RFC3987]]) of the namespace definition. Value MUST be in the form of a non-relative IRI. | | prefix | `string` | The prefix to be used for the [name](#xml-name). | -| attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. If `nodeType` is present, this field MUST NOT be present.

**Deprecated:** Use `nodeType: attribute` in place of `attribute: true` | -| wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `"array"` (outside the `items`). If `nodeType` is present, this field MUST NOT be present.

**Deprecated:** Set `nodeType: element` explicitly in place of `wrapped: true` | +| attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. If `nodeType` is present, this field MUST NOT be present.

**Deprecated:** Use `nodeType: "attribute"` in place of `attribute: true` | +| wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `"array"` (outside the `items`). If `nodeType` is present, this field MUST NOT be present.

**Deprecated:** Set `nodeType: "element"` explicitly in place of `wrapped: true` | Note that when generating an XML document from object data, the order of the nodes is undefined. Use `prefixItems` to control node ordering. @@ -3112,10 +3112,10 @@ The `none` type is useful for JSON Schema constructs that require more Schema Ob ###### Modeling Element Lists -For historical compatibility, schemas of `type: array` default to `nodeType: none`, placing the nodes for each array item directly under the parent node. +For historical compatibility, schemas of `type: array` default to `nodeType: "none"`, placing the nodes for each array item directly under the parent node. This also aligns with the inferred naming behavior defined under [XML Node Names](#xml-node-names). -To produce an element wrapping the list, set an explicit `nodeType: element` on the `type: array` schema. +To produce an element wrapping the list, set an explicit `nodeType: "element"` on the `type: array` schema. When doing so, it is advisable to set an explicit name on either the wrapping element or the item elements to avoid them having the same inferred name. See examples for expected behavior. From ebf62516147118d7e2cdb1e88a4a5bba3cf4bd57 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 15 May 2025 19:42:28 -0700 Subject: [PATCH 5/9] A bit more formatting improvements --- src/oas.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/oas.md b/src/oas.md index ffbf6722c5..07225947d9 100644 --- a/src/oas.md +++ b/src/oas.md @@ -3083,7 +3083,7 @@ When using a Schema Object with XML, if no XML Object is present, the behavior i | Field Name | Type | Description | | ---- | :----: | ---- | -| 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. | +| 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. | | name | `string` | Sets the name of the element/attribute corresponding to the schema, replacing name that was inferred as described under [XML Node Names](#xml-node-names). This field SHALL be ignored if the `nodeType` is `text`, `cdata`, or `none`. | | namespace | `string` | The IRI ([[RFC3987]]) of the namespace definition. Value MUST be in the form of a non-relative IRI. | | prefix | `string` | The prefix to be used for the [name](#xml-name). | @@ -3112,10 +3112,10 @@ The `none` type is useful for JSON Schema constructs that require more Schema Ob ###### Modeling Element Lists -For historical compatibility, schemas of `type: array` default to `nodeType: "none"`, placing the nodes for each array item directly under the parent node. +For historical compatibility, schemas of `type: "array"` default to `nodeType: "none"`, placing the nodes for each array item directly under the parent node. This also aligns with the inferred naming behavior defined under [XML Node Names](#xml-node-names). -To produce an element wrapping the list, set an explicit `nodeType: "element"` on the `type: array` schema. +To produce an element wrapping the list, set an explicit `nodeType: "element"` on the `type: "array"` schema. When doing so, it is advisable to set an explicit name on either the wrapping element or the item elements to avoid them having the same inferred name. See examples for expected behavior. @@ -3240,7 +3240,7 @@ properties: value ``` -The `name` field for the `type: array` schema has no effect because the default `nodeType` for that object is `none`: +The `name` field for the `type: "array"` schema has no effect because the default `nodeType` for that object is `none`: ```yaml properties: From 530bfa71c2df95cf128cb703134bebb827bdcbfb Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 16 May 2025 11:34:38 -0700 Subject: [PATCH 6/9] Fix missing word Co-authored-by: Ralf Handl --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 07225947d9..6664dca11b 100644 --- a/src/oas.md +++ b/src/oas.md @@ -3084,7 +3084,7 @@ When using a Schema Object with XML, if no XML Object is present, the behavior i | Field Name | Type | Description | | ---- | :----: | ---- | | 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. | -| name | `string` | Sets the name of the element/attribute corresponding to the schema, replacing name that was inferred as described under [XML Node Names](#xml-node-names). This field SHALL be ignored if the `nodeType` is `text`, `cdata`, or `none`. | +| name | `string` | Sets the name of the element/attribute corresponding to the schema, replacing the name that was inferred as described under [XML Node Names](#xml-node-names). This field SHALL be ignored if the `nodeType` is `text`, `cdata`, or `none`. | | namespace | `string` | The IRI ([[RFC3987]]) of the namespace definition. Value MUST be in the form of a non-relative IRI. | | prefix | `string` | The prefix to be used for the [name](#xml-name). | | attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. If `nodeType` is present, this field MUST NOT be present.

**Deprecated:** Use `nodeType: "attribute"` in place of `attribute: true` | From bd7e2614b4e63c05ab5366dc1e2d54d42e46edc4 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 16 May 2025 11:55:19 -0700 Subject: [PATCH 7/9] Make the DOM reference normative --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index 6664dca11b..d5931a2aae 100644 --- a/src/oas.md +++ b/src/oas.md @@ -3099,8 +3099,8 @@ This object MAY be extended with [Specification Extensions](#specification-exten ##### XML Node Types -Each Schema Object describes a particular type of XML [node](https://dom.spec.whatwg.org/#interface-node) which is specified by the `nodeType` field, which has the following possible values. -Except for the special value `none`, these values have numeric equivalents in the DOM [specification](https://dom.spec.whatwg.org/#interface-node) which are given in parentheses after the name: +Each Schema Object describes a particular type of XML [[!DOM]] [node](https://dom.spec.whatwg.org/#interface-node) which is specified by the `nodeType` field, which has the following possible values. +Except for the special value `none`, these values have numeric equivalents in the DOM specification which are given in parentheses after the name: * `element` (1): The schema represents an element and describes its contents * `attribute` (2): The schema represents an attribute and describes its value From 448cab3a07615b85b98171f83b97e5fd37973744 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 16 May 2025 11:56:22 -0700 Subject: [PATCH 8/9] Improved wording around nodeType: none --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index d5931a2aae..e21724c2d2 100644 --- a/src/oas.md +++ b/src/oas.md @@ -3106,7 +3106,7 @@ Except for the special value `none`, these values have numeric equivalents in th * `attribute` (2): The schema represents an attribute and describes its value * `text` (3): The schema represents a text node (parsed character data) * `cdata` (4): The schema represents a CDATA section -* `none`: The schema does not correspond to any node in the XML document, and its contents are included directly under the parent schema's node +* `none`: The schema does not correspond to any node in the XML document, and the nodes corresponding to its subschema(s) are included directly under its parent schema's node The `none` type is useful for JSON Schema constructs that require more Schema Objects than XML nodes, such as a schema containing only `$ref` that exists to facilitate re-use rather than imply any structure. From 630cc2a148298e408312a247bffac779d278cbee Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 19 May 2025 09:32:55 -0700 Subject: [PATCH 9/9] Expand examples, link from field description. --- src/oas.md | 157 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 145 insertions(+), 12 deletions(-) diff --git a/src/oas.md b/src/oas.md index e21724c2d2..5115f73022 100644 --- a/src/oas.md +++ b/src/oas.md @@ -3091,7 +3091,7 @@ When using a Schema Object with XML, if no XML Object is present, the behavior i | wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `"array"` (outside the `items`). If `nodeType` is present, this field MUST NOT be present.

**Deprecated:** Set `nodeType: "element"` explicitly in place of `wrapped: true` | Note that when generating an XML document from object data, the order of the nodes is undefined. -Use `prefixItems` to control node ordering. +Use `prefixItems` to control node ordering as shown under [Ordered Elements and Text](#ordered-elements-and-text). See [Appendix B](#appendix-b-data-type-conversion) for a discussion of converting values of various types to string representations. @@ -3402,35 +3402,168 @@ components: ``` -###### Element With Text Before and After a Child Element +Alternatively, the named root element could be set at the point of use and the root element disabled on the component: -In this example, `prefixItems` is used to control the ordering. -Since `prefixItems` works with arrays, we need to explicitly set the `nodeType` to `element`. -Within `prefixItems`, we need to explicitly set the `nodeType` of the `text` nodes, but do not need a name, while the data node's default `nodeType` of `element` is correct, but it needs an explicit `name`: +```yaml +paths: + /docs: + get: + responses: + "200": + content: + application/xml: + xml: + nodeType: element + name: StoredDocument + $ref: "#/components/schemas/Documentation" + put: + requestBody: + required: true + content: + application/xml: + xml: + nodeType: element + name: UpdatedDocument + $ref: "#/components/schemas/Documentation" + responses: + "201": {} +components: + schemas: + Documentation: + xml: + nodeType: none + type: object + properties: + content: + type: string + contentMediaType: text/html + xml: + nodeType: cdata +``` + +The GET response XML: + +```xml + + Awesome Docs]]> + +``` + +The PUT request XML: + +```xml + + Awesome Docs]]> + +``` + +The in-memory instance data for all three of the above XML documents: + +```json +{ + "content": "Awesome Docs" +} +``` + +###### Ordered Elements and Text + +To control the exact order of elements, use the `prefixItems` keyword. +With this approach, it is necessary to set the element names using the XML Object as they would otherwise all inherit the parent's name despite being different elements in a specific order. +It is also necessary to set `nodeType: "element"` explicitly on the array in order to get an element containing the sequence. + +This first ordered example shows a sequence of elements, as well as the recommended serialization of `null` for elements: ```yaml components: schemas: - Report: + OneTwoThree: + xml: + nodeType: element type: array + minLength: 3 + maxLength: 3 + prefixItems: + - xml: + name: One + type: string + - xml: + name: Two + type: object + required: + - unit + - value + properties: + unit: + type: string + xml: + nodeType: attribute + value: + type: number + xml: + nodeType: text + - xml: + name: Three + type: + - boolean + - "null" +``` + +```xml + + Some text + 42 + + +``` + +The in-memory instance data that would produce the above XML snippet with the preceding schema would be: + +```json +[ + "Some Text", + { + "unit": "cubits", + "value": 42 + }, + null +] +``` + +In this next example, the `name` needs to be set for the element, while the `nodeType` needs to be set for the text nodes. + +```yaml +components: + schemas: + Report: xml: nodeType: element + type: array prefixItems: - - type: string - xml: + - xml: nodeType: text - - type: number - xml: + type: string + - xml: name: data - - type: string - xml: + type: number + - xml: nodeType: text + type: string ``` ```xml Some preamble text.42Some postamble text. ``` +The in-memory instance data structure for the above example would be: + +```json +[ + "Some preamble text." + 42, + "Some postamble text." +] +``` + #### Security Scheme Object Defines a security scheme that can be used by the operations.