OpenAPI-Specification
OpenAPI-Specification copied to clipboard
OAI
XML Object - an incomprehensible sentence
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.
@hrennau , here's how I interpret that sentence:
Each of the following examples has three code snippets:
- 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.
- The same Schema Object in YAML syntax.
- 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.
