Example(s) in Content Type Objects

[darrelmiller]

In the definition of a Content Type Object we currently allow either an array of 'examples' or a single 'example' object.

There are conflicting opinions on how we should do this:

• Only have an example object and allow secondary examples to be defined using x- extensions
• Only have an examples array and require a single item array for single examples
• Add another object layer in examples array to provide example metadata, to be able to make a distinction between the examples.
• Leave it as is and support both example and examples

[DavidBiesack]

I vote against using x- extensions. that renders them generally unusable by OpenAPI tools.

I would like to see each example be an Example Object with at least a description, as may examples require or benefit from at least some explanation.

I like the freedom of either singular example or examples but not both (i.e. oneOf). It's a simple transformation from singular to list in tools. We should support the examples array. Most cases probably have only one example, but we should not make it more cumbersome the majority by requiring examples: [ ... ]