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

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?