Is "examples" (plural) supported inside schemas in 3.0.x?

[hkosova]

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-example

However, 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?

[darrelmiller]

@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.

[handrews]

@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.

[chrisdostert]

@darrelmiller curious about your thoughts as to what it would take to get this added?

[ntrepid8]

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.

[mindstretch23]

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 = )

[handrews]

@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.

[hkosova]

Closing - the example mentioned in the original post is a mistake, it will be removed by PR #2042.