Add examples object #636

fehguy · 2016-04-08T13:22:41Z

Fixes #544

DO NOT MERGE--needs documentation updates.

ePaul · 2016-04-08T17:29:32Z

versions/3.0.md

@@ -1152,6 +1152,51 @@ name: pet
 description: Pets operations
 ```

+#### <a name="examplesObject"></a>Examples Object
+
+Anywhere an `example` may be given, allow a $ref object.  This does mean that `example` can be either a string primitive or an object, like `additionalProperties`:


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.

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

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

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

@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 · 2016-04-11T00:38:05Z

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 · 2016-04-11T20:55:58Z

@OAI/tdc please approve or reject

darrelmiller · 2016-04-12T01:58:43Z

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 · 2016-04-12T05:30:50Z

@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 · 2016-04-13T02:50:35Z

versions/3.0.md

+
+In locations where the field being provided an `example` is a scalar value _or_ has it's content-type definition determined by a higher-level construct (a response payload, for example, uses the `produces` attribute to select the correct message format), the plural `examples` shall be used, and the payload format be specified as a key to the example.
+
+In all cases, the payload is expected to be compatible with the type schema for the value that it is accompanying. Tooling vendors may choose to valide compatibility automatically, and reject the example value(s) if they are not compatible.


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

jharmn · 2016-04-13T02:56:16Z

@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 · 2016-04-14T04:43:58Z

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

earth2marsh · 2016-04-14T04:53:57Z

👍

jharmn · 2016-04-14T13:24:34Z

👍

Add examples object [Manually ported merge] Co-authored-by: Tony Tam <tony@eatbacon.org>

adde examples object

6c21f32

fehguy added the OpenAPI.Next Proposal label Apr 8, 2016

ePaul reviewed Apr 8, 2016
View reviewed changes

clarifications

6bb80f8

DavidBiesack mentioned this pull request Apr 12, 2016

Clarify File Structure and use of $ref JSON Reference/Pointer #648

Closed

jharmn changed the title ~~adde examples object~~ Add examples object Apr 13, 2016

jharmn reviewed Apr 13, 2016
View reviewed changes

fehguy merged commit c630636 into OpenAPI.next Apr 14, 2016

jharmn mentioned this pull request Apr 25, 2016

Request bodies moved out of parameters #670

Merged

ePaul mentioned this pull request Apr 25, 2016

support references for examples #625

Closed

webron mentioned this pull request May 3, 2016

Change the behavior of default parameter values swagger-api/swagger-ui#1258

Closed

darrelmiller mentioned this pull request Aug 21, 2016

Proposal to enable support for alternate schemas #764

Closed

DavidBiesack mentioned this pull request Aug 22, 2016

Parameters Object does not list examples field #766

Closed

fehguy deleted the issue-544 branch October 20, 2016 17:12

handrews mentioned this pull request Jun 9, 2024

Consolidate guidance around examples (3.0.4) #3893

Merged

handrews added a commit to handrews/OpenAPI-Specification that referenced this pull request Oct 11, 2024

Merge pull request OAI#636 from OAI/issue-544

1cbf196

Add examples object [Manually ported merge] Co-authored-by: Tony Tam <tony@eatbacon.org>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add examples object #636

Add examples object #636

fehguy commented Apr 8, 2016

ePaul Apr 8, 2016

webron Apr 11, 2016

ePaul Apr 11, 2016

webron Apr 12, 2016

ePaul Apr 12, 2016

webron commented Apr 11, 2016

fehguy commented Apr 11, 2016

darrelmiller commented Apr 12, 2016

webron commented Apr 12, 2016

jharmn Apr 13, 2016

jharmn commented Apr 13, 2016

fehguy commented Apr 14, 2016

earth2marsh commented Apr 14, 2016

jharmn commented Apr 14, 2016


		In locations where the field being provided an `example` is a scalar value _or_ has it's content-type definition determined by a higher-level construct (a response payload, for example, uses the `produces` attribute to select the correct message format), the plural `examples` shall be used, and the payload format be specified as a key to the example.

		In all cases, the payload is expected to be compatible with the type schema for the value that it is accompanying. Tooling vendors may choose to valide compatibility automatically, and reject the example value(s) if they are not compatible.

Add examples object #636

Add examples object #636

Conversation

fehguy commented Apr 8, 2016

ePaul Apr 8, 2016

Choose a reason for hiding this comment

webron Apr 11, 2016

Choose a reason for hiding this comment

ePaul Apr 11, 2016

Choose a reason for hiding this comment

webron Apr 12, 2016

Choose a reason for hiding this comment

ePaul Apr 12, 2016

Choose a reason for hiding this comment

webron commented Apr 11, 2016

fehguy commented Apr 11, 2016

darrelmiller commented Apr 12, 2016

webron commented Apr 12, 2016

jharmn Apr 13, 2016

Choose a reason for hiding this comment

jharmn commented Apr 13, 2016

fehguy commented Apr 14, 2016

earth2marsh commented Apr 14, 2016

jharmn commented Apr 14, 2016