api-with-examples.yaml: `example` vs `examples` in Media Type Object

[tfesenko]

Thank you for merging PR #985 and providing official examples of OpenAPI v3 files! 👏👏👏

Is it possible that api-with-examples.yaml has errors?

I am asking because I validated all four examples/v3.0/ files with JSON Schema created by @timburks and @MikeRalphson. The JSON Schema validation is OK on petstore-expanded.yaml, petstore.yaml, and uber.yaml, but fails on api-with-examples.yaml.

Validation fails on content examples - there are four examples in the file, the first of which is defined on line 16:

 content:
 application/json:
 examples: 
 - {
 "versions": [
 {<...>}, {<...>}]
 } 

Media Type Object can define examples in two ways:

• example (singular) - inlines example text directly (Any in JSON Schema);
• examples (plural) - uses the Example Object, which also provides additional information, such as example name, summary, or description.

The problem is that api-with-examples.yaml defines examples with examples, but inlines them as if they were defined with example.
In my understanding of the spec, api-with-examples.yaml should be corrected:

1. Either examples keyword should be replaced by example:

 content:
 application/json:
 example: 
 {
 "versions": [
 {<...>}, {<...>}]
 } 

2. Or, we should use a real named example object where the example snippet is defined in value (or externalValue):

 content:
 application/json:
 examples: 
 versions-example:
 summary: Versions Example in JSON
 value: {
 "versions": [
 {<...>}, {<...>}]
 } 

Can you please clarify the usage of the examples keyword in api-with-examples.yaml?

[darrelmiller]

These examples need to be fixed. Sorry for the confusion

[zbinlin]

@darrelmiller The examples incompatible JSON Schema's exampes, JSON Schema's examples MUST be an array but there examples is an object.

[handrews]

@zbinlin OpenAPI's examples is not a schema keyword. It is directly under the media type, adjacent to the schema keyword. While the usage difference is unfortunate, it is not a syntactical conflict.

[MikeRalphson]

Closing as #1286 was merged. Thanks all.