Updated Examples

[darrelmiller]

This proposal attempts to address the issues raised in #488

The "Example Object" has been updated. This object now supports the following scenarios:
a) multiple examples are required,
b) when short summary or long description is needed, or
c) when an example needs to be reused using a reference object.

examples:
  cat:
    summary: Big cat example
    value:
      name: Puma
      id: 1
  dog:
    summary: Family Dog
    description: This is the story about Ferguson the dog ...
    value:
      name: Ferguson
      id: 2
  frog:
    $ref: "#/components/examples/frog"

For simpler scenarios where only one example is required, you can inline a single example.

example:
    name: Ferguson
    id: 2

For scenarios where the example is for a media type that is not JSON or YAML the value can be externalized using the externalValue property instead of the value property. The value retrieved when dereferencing this URL must match the media type/ encoding associated with described example object.

  'application/xml':
    examples:
      user:
        summary: User Example in XML
        externalValue: http://foo.bar/examples/user-example.xml

For Content Objects, Parameter Objects and Header Objects, you can use either a inline example or a map of described example objects called examples , but not both. Schema objects only support inline example as in OpenAPI V2.

[whitlockjc]

Does this address a specific issue?

[darrelmiller]

@whitlockjc Yes, #488

[DavidBiesack]

I recommend simpler terminology -- Example Object for example' and Examples Objectrather thanDescribed Example Objectfor this new object. (It's plural since it is a map, i.e. a container of multiple examples). The two are distinct, and I think they should be mutually exclusive (asexampleandexamples` are now.) This just replaces the examples array with an Examples object.

[darrelmiller]

@DavidBiesack But the "described example object" that is mapped by the "examples" object is not the same object as is used in "example". That's why we have the new name. It has the summary, description and value property. There isn't much benefit in creating a distinct object for the map of "described example objects" which is why I just identified it as a Map. This is a convention we started using in Components.
It might be possible to not use "example object" in the "example" property and just use "any" as is done in the schema object and then we could reclaim "example object" to be what I have called "described example object". The only downside there is we lose the place to document the fact that the "example object" is a literal value or a string that contains an escaped example.

[DavidBiesack]

I would prefer to rename the existing Example Object since it is not an object (in the JSON sense), it is really just an Example Value (may be a non-object number, string, boolean, array). Rename your Described Example Object as Example Object. Then your Examples Object could be a map of Example Objects each of which has summary, description, value, x-^ . Further, any $ref for an example must be only within examples Examples Object; one cannot use $ref in an example Also, consider changing valueUri to use $ref

[DavidBiesack]

I suggest renaming Example Object as Example Value since it is not an JSON object

[darrelmiller]

That seems like a reasonable approach. I must admit, I did like the "Described Example" moniker but Example Value is more accurate than Example Object for the current usage.

[DavidBiesack]

(Funny.. I felt the Described Example moniker was slightly awkward.)

[darrelmiller]

It's ok, I'm not too emotionally attached to it :-)

[earth2marsh]

If the valueUrl concept survives, consider whether having a name that is more similar to externalDocs which has some similarities here (non-$ref style references), like externalValue or externalExample

[darrelmiller]

Done

[DavidBiesack]

... then this can be Example Object

[DavidBiesack]

... then this could be Map[string, Example Object]

[DavidBiesack]

suggest changing to Example Value and "example value SHOULD ..."

[DavidBiesack]

Map[ string, Example Object ...

[DavidBiesack]

becomes <a name="exampleValue"></a>Example Value

[DavidBiesack]

becomes Example Value Example

[DavidBiesack]

becomes <a name="exampleObject"></a>Example Object

[DavidBiesack]

drop "described" throughout

[DavidBiesack]

I suggest using $ref : uri instead of valueUri.
This way, it can also be a pointer to a value elsewhere in the OpenAPI definition, or it can be an external resource

[darrelmiller]

It can't be done like that as then we would lose the summary and description properties. The alternative would be this:

examples:
  foo: 
    summary: this is a referenced example value
    value:
      $ref: http://example.com/reuse.json#/example/one

The downside to this, is that you can no longer reference example values that are not JSON or YAML. Based on the conversation with @fehguy the other day, I am recommending that we add wording to the reference object definition that $ref can only point to JSON or YAML content.
By using valueUrl we can have something special for examples that may be other formats. (and later schemas, but shhhhhh, don't say that out loud).

The other reason I decided against using reference objects in the value property is that you can already reference described examples either in the current document or externally, so why do we also need to reference the value. If you are going to re-use, you would likely want the summary/description too.

[darrelmiller]

Changed made based on TDC review.

• Described Example Object becomes Example Object
• The old example goes away and we now just use Any for the type of example.
• valueUrl has been renamed to externalValue.

[fehguy]

Looks good to me!

[raymondfeng]

LGTM

[webron]

openapi.json

[webron]

Overall, looks good. Some of my comments are nitpicking, one or two are note. Other than that, .

[webron]

The Content-Type is set to *?

[whitlockjc]

Shouldn't it be */*?

[webron]

It should be. The comment itself doesn't seem in place though because nothing in the example describes a wildcard content type.

[webron]

I don't think so...

[whitlockjc]

Great job merging your conflict @darrelmiller. 🥇 (joke of course)

[webron]

If we dropped examples, this needs to change.

[whitlockjc]

Why would we support example and examples elsewhere but not here? Was removing this intentional? It doesn't seem to be because on line 2812 you use examples.

[webron]

The idea behind removing examples was that unlike other places, there's no content here and no media types described. Providing multiple examples for a model is out of context and doesn't serve a lot of value. You'd need to combine the schema with a media type to define how it's actually serialized. You could argue that even the example should be dropped for that reason.

[webron]

same as above

[whitlockjc]

To me, "correct format" makes sense but should we be more explicit, something to the effect of "it should adhere to the schema specified in the parameter encoding"?

[darrelmiller]

There are two issues here. If the parameter encoding says XML, then the example needs to be XML. That's what I meant by correct format. Saying that the example should conform to the schema is a different requirement. Let me try and come up with words that say both.

[webron]

"it should make sense, don't do anything crazy"

[whitlockjc]

Same as above.

[whitlockjc]

I don't understand the value. Since examples is no longer an array if items, what is the significance of the map key?

[whitlockjc]

It appears to be a free-form description/label/name but the intent is not explained in the "Examples Object" description.

[DavidBiesack]

The key allows referencing/reusing the specific example in a $ref

[whitlockjc]

I forgot to start a review, my bad. Review done, comments above.