diff --git a/src/oas.md b/src/oas.md
index 0624358d25..1d162e06ee 100644
--- a/src/oas.md
+++ b/src/oas.md
@@ -3274,46 +3274,85 @@ For examples using `attribute` or `wrapped`, please see version 3.1 of the OpenA
###### No XML Object
-Basic string property (`nodeType` is `element` by default):
+Basic string property without an XML Object, using `serializedValue` (the remaining examples will use `externalSerializedValue` so that the XML form can be shown with syntax highlighting):
```yaml
-properties:
- animals:
- type: string
-```
-
-```xml
-...
+application/xml:
+ schema:
+ type: object
+ xml:
+ name: document
+ properties:
+ animals:
+ type: string
+ examples:
+ pets:
+ dataValue:
+ animals: "dog, cat, hamster"
+ serializedValue: |
+
+ dog, cat, hamster
+
```
Basic string array property (`nodeType` is `none` by default):
```yaml
-properties:
- animals:
- type: array
- items:
- type: string
+application/xml:
+ schema:
+ type: object
+ xml:
+ name: document
+ properties:
+ animals:
+ type: array
+ items:
+ type: string
+ examples:
+ pets:
+ dataValue:
+ animals: [dog, cat, hamster]
+ externalSerializedValue: ./examples/pets.xml
```
+Where `./examples/pets.xml` would be:
+
```xml
-...
-...
-...
+
+ dog
+ cat
+ hamster
+
```
###### XML Name Replacement
```yaml
-properties:
- animals:
- type: string
+application/xml:
+ schema:
+ type: object
xml:
- name: animal
+ name: document
+ properties:
+ animals:
+ type: string
+ xml:
+ name: animal
+ examples:
+ pets:
+ dataValue:
+ animals: [dog, cat, hamster]
+ externalSerializedValue: ./examples/pets.xml
```
+Where `./examples/pets.xml` would be:
+
```xml
-...
+
+ dog
+ cat
+ hamster
+
```
###### XML Attribute, Prefix and Namespace
@@ -3336,8 +3375,22 @@ components:
xml:
namespace: https://example.com/schema/sample
prefix: sample
+ requestBodies:
+ Person:
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Person"
+ examples:
+ Person:
+ dataValue:
+ id: 123
+ name: example
+ externalSerializedValue: ./examples/Person.xml
```
+Where `./examples/Person.xml` would be:
+
```xml
example
@@ -3349,126 +3402,216 @@ components:
Changing the element names:
```yaml
-properties:
- animals:
- type: array
- items:
- type: string
- xml:
- name: animal
+application/xml:
+ schema:
+ type: object
+ xml:
+ name: document
+ properties:
+ animals:
+ type: array
+ items:
+ type: string
+ xml:
+ name: animal
+ examples:
+ pets:
+ dataValue:
+ animals: [dog, cat, hamster]
+ externalSerializedValue: ./examples/pets.xml
```
+Where `./examples/pets.xml` would be:
+
```xml
-value
-value
+
+ dog
+ cat
+ hamster
+
```
The `name` field for the `type: "array"` schema has no effect because the default `nodeType` for that object is `none`:
```yaml
-properties:
- animals:
- type: array
- items:
- type: string
- xml:
- name: animal
+application/xml:
+ schema:
+ type: object
xml:
- name: aliens
+ name: document
+ properties:
+ animals:
+ type: array
+ xml:
+ name: aliens
+ items:
+ type: string
+ xml:
+ name: animal
+ examples:
+ pets:
+ dataValue:
+ animals: [dog, cat, hamster]
+ externalSerializedValue: ./examples/pets.xml
```
+Where `./examples/pets.xml` would be:
+
```xml
-value
-value
+
+ dog
+ cat
+ hamster
+
```
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
-properties:
- animals:
- type: array
- items:
- type: string
+application/xml:
+ schema:
+ type: object
xml:
- nodeType: element
+ name: document
+ properties:
+ animals:
+ type: array
+ xml:
+ nodeType: element
+ items:
+ type: string
+ examples:
+ pets:
+ dataValue:
+ animals: [dog, cat, hamster]
+ externalSerializedValue: ./examples/pets.xml
```
+Where `./examples/pets.xml` would be:
+
```xml
-
- value
- value
-
+
+
+ dog
+ cat
+ hamster
+
+
```
To overcome the naming problem in the example above, the following definition can be used:
```yaml
-properties:
- animals:
- type: array
- items:
- type: string
- xml:
- name: animal
+application/xml:
+ schema:
+ type: object
xml:
- nodeType: element
+ name: document
+ properties:
+ animals:
+ type: array
+ xml:
+ nodeType: element
+ items:
+ type: string
+ xml:
+ name: animal
+ examples:
+ pets:
+ dataValue:
+ animals: [dog, cat, hamster]
+ externalSerializedValue: ./examples/pets.xml
```
+Where `./examples/pets.xml` would be:
+
```xml
-
- value
- value
-
+
+
+ dog
+ cat
+ hamster
+
+
```
Affecting both wrapping element and item element names:
```yaml
-properties:
- animals:
- type: array
- items:
- type: string
- xml:
- name: animal
+application/xml:
+ schema:
+ type: object
xml:
- name: aliens
- nodeType: element
+ name: document
+ properties:
+ animals:
+ type: array
+ xml:
+ name: aliens
+ nodeType: element
+ items:
+ type: string
+ xml:
+ name: animal
+ examples:
+ pets:
+ dataValue:
+ animals: [dog, cat, hamster]
+ externalSerializedValue: ./examples/pets.xml
```
+Where `./examples/pets.xml` would be:
+
```xml
-
- value
- value
-
+
+
+ dog
+ cat
+ hamster
+
+
```
If we change the wrapping element name but not the item element names:
```yaml
-properties:
- animals:
- type: array
- items:
- type: string
+application/xml:
+ schema:
+ type: object
xml:
- name: aliens
- nodeType: element
+ name: document
+ properties:
+ animals:
+ type: array
+ xml:
+ name: aliens
+ nodeType: element
+ items:
+ type: string
+ examples:
+ pets:
+ dataValue:
+ animals: [dog, cat, hamster]
+ externalSerializedValue: ./examples/pets.xml
```
+Where `./examples/pets.xml` would be:
+
```xml
-
- value
- value
-
+
+
+ dog
+ cat
+ hamster
+
+
```
###### Elements With Attributes And Text
```yaml
-properties:
- animals:
+application/xml:
+ schema:
type: array
xml:
nodeType: element
@@ -3481,12 +3624,21 @@ properties:
type: string
xml:
nodeType: attribute
- content:
+ name:
type: string
xml:
nodeType: text
+ examples:
+ pets:
+ dataValue:
+ - kind: Cat
+ name: Fluffy
+ - kind: Dog
+ name: Fido
```
+Where `./examples/pets.xml` would be:
+
```xml
Fluffy
@@ -3500,15 +3652,6 @@ In this example, no element is created for the Schema Object that contains only
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:
- schema:
- $ref: "#/components/schemas/Documentation"
components:
schemas:
Documentation:
@@ -3519,8 +3662,20 @@ components:
contentMediaType: text/html
xml:
nodeType: cdata
+ responses:
+ content:
+ application/xml:
+ schema:
+ $ref: "#/components/schemas/Documentation"
+ examples:
+ docs:
+ dataValue:
+ content: Awesome Docs
+ externalSerializedValue: ./examples/docs.xml
```
+Where `./examples/docs.xml` would be:
+
```xml
Awesome Docs]]>
@@ -3542,6 +3697,10 @@ paths:
nodeType: element
name: StoredDocument
$ref: "#/components/schemas/Documentation"
+ examples:
+ stored:
+ externalDataValue: ./examples/content.json
+ externalSerializedValue: ./examples/stored.xml
put:
requestBody:
required: true
@@ -3552,6 +3711,10 @@ paths:
nodeType: element
name: UpdatedDocument
$ref: "#/components/schemas/Documentation"
+ examples:
+ updated:
+ externalDataValue: ./examples/content.json
+ externalSerializedValue: ./examples/updated.xml
responses:
"201": {}
components:
@@ -3568,7 +3731,15 @@ components:
nodeType: cdata
```
-The GET response XML:
+where `./examples/content.json` would be:
+
+```json
+{
+ "content": "Awesome Docs"
+}
+```
+
+`./examples/stored.xml` would be:
```xml
@@ -3576,7 +3747,7 @@ The GET response XML:
```
-The PUT request XML:
+and `./examples/updated.xml` would be:
```xml
@@ -3584,14 +3755,6 @@ The PUT request XML:
```
-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.
@@ -3601,40 +3764,53 @@ It is also necessary to set `nodeType: "element"` explicitly on the array in ord
This first ordered example shows a sequence of elements, as well as the recommended serialization of `null` for elements:
```yaml
-components:
- schemas:
+application/xml:
+ schema:
+ xml:
+ nodeType: element
+ name: OneTwoThree
+ 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"
+ examples:
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"
+ dataValue: [
+ "Some text",
+ {
+ "unit": "cubits"
+ "value": 42
+ },
+ null
+ ]
+ externalSerializedValue: ./examples/OneTwoThree.xml
```
+Where `./examples/OneTwoThree.xml` would be:
+
```xml
Some text
@@ -3643,61 +3819,52 @@ components:
```
-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:
+application/xml:
+ schema:
+ xml:
+ nodeType: element
+ name: Report
+ type: array
+ prefixItems:
+ - xml:
+ nodeType: text
+ type: string
+ - xml:
+ name: data
+ type: number
+ - xml:
+ nodeType: text
+ type: string
+ examples:
Report:
- xml:
- nodeType: element
- type: array
- prefixItems:
- - xml:
- nodeType: text
- type: string
- - xml:
- name: data
- type: number
- - xml:
- nodeType: text
- type: string
+ dataValue: [
+ "Some preamble text.",
+ 42,
+ "Some postamble text."
+ ]
+ externalSerializedValue: ./examples/Report.xml
```
+Where `./examples/Report.xml` would be:
+
```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."
-]
-```
-
###### XML With `null` Values
Recall that the schema validates the in-memory data, not the XML document itself.
-The properties of the `"related"` element object are omitted for brevity as it is here to show how the `null` value is represented.
+This example does not define properties for `"related"` as it is showing how
+empty objects and `null` are handled.
```yaml
-product:
+appliaction/xml:
+schema:
+ xml:
+ name: product
type: object
required:
- count
@@ -3720,8 +3887,25 @@ product:
type:
- object
- "null"
+examples:
+ productWithNulls:
+ dataValue: {
+ "count": null,
+ "description": "Thing",
+ "related": null
+ }
+ externalSerializedValue: ./examples/productWithNulls.xml
+ productNoNulls:
+ dataValue: {
+ "count": 42,
+ "description: "Thing"
+ "related": {}
+ }
+ externalSerializedValue: ./examples/productNoNulls.xml
```
+Where `./examples/productWithNulls.xml` would be:
+
```xml
Thing
@@ -3729,16 +3913,13 @@ product:
```
-The above XML example corresponds to the following in-memory instance:
+and `./examples/productNoNulls.xml` would be:
-```json
-{
- "product": {
- "count": null,
- "description": "Thing",
- "related": null
- }
-}
+```xml
+
+ Thing
+
+
```
#### Security Scheme Object