Is "examples" (plural) supported inside schemas in 3.0.x?
hkosova opened this issue · 7 comments
OpenAPI Specification versions: 3.0.0, 3.0.1
The Example Object Example section demonstrates the usage of the examples (plural) keyword inside a schema:
# in a model
schemas:
properties:
name:
type: string
examples:
name:
$ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-exampleHowever, the Schema Object description only mentions the example keyword (singular) but not examples (plural).
Is examples actually supported inside schemas?
Or is the abovementioned example invalid?
@hkosova That's an error in my opinion. Our goal was to bring our schema object closer to JSON Schema, not to add more stuff to it.
@darrelmiller @hkosova as of draft-06, JSON Schema has examples, which is an array. It's suggested but not required that the elements of the array be valid examples. It's just a RECOMMENDED rather than MUST because we thought maybe people would want to try other structures than just an array.
@darrelmiller curious about your thoughts as to what it would take to get this added?
If examples is not going to be added any time soon, could a note be added to the Docs to save folks from trying to use something that will not validate? The swagger.io docs have this note:
Note that schemas and properties support singular example but not plural examples.
Also, it would be cool if items in the examples array supported a $ref: '#/components/examples/my-example style reference rather than just a literal.
Is there any plan to support examples in schemas section? This would be really useful. Based on @handrews comment, sounds like its already supported by JSON schema, so it wouldn't be adding stuff to the JSON schema = )
@mindstretch23 assuming alternativeSchema makes it into 3.1, and tooling vendors start supporting modern drafts (most likely the really-soon-now-I-promise draft-08), you would be able to use any JSON Schema feature that tool vendors recognize.