Add examples object

[fehguy]

Fixes #544

DO NOT MERGE--needs documentation updates.

[ePaul]

This is a change to the 2.0 behavior, where the example property of a model is of the same type as what the model described. (I.e. type: object means it would be an object, type: string means it is a string, type: number means it is a number.) Now it seems to be a string containing formatted JSON (or a reference to such)?

If this is intentional, that needs to be updated too.

[webron]

@ePaul actually, in 2.0 it is the default field value has to be the same type as it's 'container' (be it a parameter or a model property). The examples have on such constraint.

[ePaul]

@webron Maybe I'm misunderstanding this. Example Object (for responses):

The name of the property MUST be one of the Operation produces values (either
implicit or inherited). The value SHOULD be an example of what such a response
would look like.

The example for this (with a JSON object) seem to indicate that this is an instance matching the schema.

In the schema object we have:

Field Name	Type	Description
example	Any	A free-form property to include a an example of an instance for this schema.

Here too, I would understand (and the examples agree) that this usually include the JSON value, not a string representation thereof. (While it might not be a "constraint", given the type "Any", the text + examples strongly suggest this.)

[webron]

@ePaul - when writing the spec, while making mistakes here and there, I've taken great care to word things as they are. Type Any means just that - any valid JSON value would fit there, regardless of what it relates to. The word SHOULD is used on purpose and not the word MUST. The spec really does not enforce any sort of constraint here, and I don't think it should (for a few reason).

Going back to the default field value, you'll see that it uses a stronger restriction saying it MUST follow the type assigned to its container.

[ePaul]

@webron Okay, maybe the spec writers meant not to put a restriction here (I guess you were there – I was not), but then I don't think this is a good idea to allow just "anything at all".
It should clearly define how the examples are meant to be used.

Allowing just strings (or refs to such) now is also okay, as long as it is made explicit.

[webron]

I'm a bit confused by this. Is this meant to add example or examples to parameters as well (which they don't right now)?

Also, adding $ref support to a primitive-valued field is a conceptual change which we haven't had until now. I'm not against it, just making sure we understand the impact of it.

[fehguy]

@OAI/tdc please approve or reject

[darrelmiller]

a) this is awesome and has a big 👍 from me
b) Am I correct in understanding that this change means that you can't blindly run an OpenAPI doc through a $ref processor because you could end up trying to merge XML into a JSON doc?
c) Maybe I'm dense, but if we allow multiple examples, don't we also need multiple schemas? Not sure how you validate a JSON schema against an XML document.

[webron]

@darrelmiller it's a bit ugly now, but technically the approach in 2.0 was that non-json complex values would be pretty much strings. The use of a reference doesn't really change that (you won't be able to magically reference an XML document because it would result in an invalid JSON).

As for the multiple schema - not necessarily. 2.0 has a single schema for JSON and XML for example, although it's obviously limited. With that, it would still be possible to provide multiple examples. This may change when we tackle the content negotiation (and thus supporting multiple schemas).

👍 from me for the proposal, but the PR does not cover the changes that need to be made in the spec itself. I can expand the PR if the proposal itself is accepted by the @OAI/tdc.

[jharmn]

@fehguy "choose to valide" => "choose to validate"

[jharmn]

@fehguy a point of confusion: you updated the "Examples Object" section (https://github.com/OAI/OpenAPI-Specification/blob/issue-544/versions/3.0.md#examples-object), but reference example throughout the copy (which would be https://github.com/OAI/OpenAPI-Specification/blob/issue-544/versions/3.0.md#exampleObject).
example is left in it's current state (type=any), and examples is now $ref-able/object (which is great, by the way). With that in mind, it might reduce confusion to change the copy to explicitly state examples (vs example), as they are quite different in their usage.
...or change how example works too, but I think that has XML implications.

[fehguy]

thanks @jasonh-n-austin. I'm going to make a note to clarify the documentation on this and we can close this out.

[earth2marsh]

👍

[jharmn]

👍