XML Object - an incomprehensible sentence

[hrennau]

In the OpenAPI spec, section "XML Object",
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#xmlObject

the examples contain text which appears to me incomprehensible:

The examples of the XML object definitions are included inside a property definition of a Schema Object with a sample of the XML representation of it.

What does this tell us? What are "examples of the XML object definitions" - the examples in the spec? What is "a property definition of a Schema Object"? Is the sentence about where to put examples of the resulting XML? I have no clue what this sentence is meant to say. And I do not think this is entirely my fault.

[tedepstein]

@hrennau , here's how I interpret that sentence:

Each of the following examples has three code snippets:

1. A Schema Object in JSON syntax. The schema would be used to define a property within an object-typed schema, though the containing object schema is omitted for brevity. Property schemas are the only context in which an XML Object is meaningful.
2. The same Schema Object in YAML syntax.
3. An abbreviated XML example conforming to the Schema Object.

Does that explain it better? If so, please feel free to submit a pull request with this change, so the Technical Specification Committee can review it. Your PR should be based on the v3.0.3-dev branch.

[handrews]

PR merged for 3.0.4 and ported to 3.1.1 via PR #3921!