Add examples field to schema objects, or allow reference objects in example fields

[dmolesUC]

Currently, example objects can be referenced from the examples fields of parameter objects and media type objects, but not from the mutually exclusive example fields of those objects, or from schema objects.

It's not obvious why schema objects are different, and in fact putting a $ref in a schema object's example field nearly works in swagger-ui. (Likely it also works with parameter objects and media type objects, although I haven't tested that.)

It would be nice if this was supported, or if not, if the rationale was clearly documented in the schema object section of the spec and in the example entries in the field tables.

(There's also the confusing Examples Object section of the spec -- not to be confused with the Example Object section, singular -- which states:

In an example, a JSON Reference MAY be used, with the explicit restriction...

# in a model
schemas:
  properties:
    name:
      type: string
      example:
        $ref: http://foo.bar#/examples/name-example

But it looks like the plural version's been removed in 3.0.1.)

[webron]

The Examples Object is an unfortunate left over that we forgot to remove before publishing 3.0.0 but because we can't change a final version, the fix went into 3.0.1. This is not too critical since nothing in the spec actually references that object and it's not being used.

Putting an example in the Schema object doesn't make a lot of sense as the format can change based on the media type that's being used. Because Schema objects are not linked to a media type, describing different ones would have been cumbersome. We kept the example field there for convenience but encourage users to use the examples field under the media types, which can also be reused.

[handrews]

In JSON Schema draft-06/wright-01 (the next one after the one OAI 3.0 uses) we added examples which is an array of elements that are likely to be literal example values but intentionally are not constrained. So having each array element be an object indexed by media type would be allowed within the spec, if that is of interest.

Otherwise, if you update JSON Schema versions again you'll probably want to forbid that. But one reason we left the array values unconstrained was to see what people would do with it other than put literal values in it. The media type thing hadn't occurred to me but seems pretty reasonable.

[handrews]

I'm going to close this out given that it's more than two years since the last answers on the thread.

Note that with OAS 3.1 updating to the latest JSON Schema, there is an examples keyword now, although it takes an array rather than an object (see #2094 for details). Since examples takes a literal value, and $ref is only allowed in a schema, no, you cannot use $ref with the JSON Schema examples inside a Schema Object.