Examples documentation #893

fehguy · 2017-02-20T23:57:14Z

Documentation clarification for example, examples

…nto issue-589-responses

fehguy · 2017-02-20T23:58:21Z

versions/3.0.md

@@ -765,7 +765,7 @@ Field Name | Type | Description
 <a name="parameterAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value should allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
 <a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.

-For more complex scenarios a `content` object can be used to define the media-type and schema of the parameter.
+For more complex scenarios a `content` object can be used to define the media-type and schema of the parameter.  Note that because the `content` object provides the appropriate serialization between examples and content serialization strategies, the `example` is not allowed in the simple `schema` scenario.


Note that we are removing support for example, examples for the simple schema case. @OAI/tdc make sure this makes sense!

The reasoning is that if examples are to be specified, there is no reason to avoid using the content object which gives explicit example format information

Ironically, we added "examples" to JSON Schema for draft 06 (which I know you're not moving to anytime soon if ever, just thought I'd mention it).

@fehguy I'm not sure I agree with this. If format is phonenumber, or postalCode you may want to include an example.

just kidding! Wanted to see if y'all were paying attention.

fehguy · 2017-02-20T23:58:42Z

versions/3.0.md

    - name: Fluffy
      petType: Cat
-    - name: Rover
-      petType: Frog
+    - {"name": "Rover", "petType": "Frog"}


These two examples are semantically equivalent

I find the json encoding inside the YAML (while correct) to be confusing; I don't think it is done elsewhere in the 3.0 spec.

fehguy · 2017-02-20T23:58:58Z

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.


With the move to requestBody, this didn't make sense anymore

fehguy · 2017-02-21T17:20:59Z

versions/3.0.md

@@ -1102,10 +1102,10 @@ application/json:
  schema:


inside a content object

Capturing a TDC discussion comment "I would expect that any tooling worth its salt would throw this out if it failed to parse, but that it would try to parse it."

whitlockjc · 2017-02-21T18:52:48Z

Does it make sense to allow a description property for the examples scenario? If I have N different examples, I'm likely showing the different valid ways this request/response could be structured and it would be nice to have a description. Yes, this would mean an object for the example instead of a string/object but it could be really useful. Thoughts?

darrelmiller · 2017-02-21T20:21:19Z

webron · 2017-02-21T20:34:17Z

@whitlockjc - @darrelmiller brought the issue up during the call. While it makes sense, to avoid the extra layer we won't support it now. Maybe in future versions.

Other than that, LGTM.

whitlockjc · 2017-02-21T20:51:11Z

DavidBiesack · 2017-02-21T20:56:16Z

versions/3.0.md

-<a name="contentTypeExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the content type.
-<a name="contentTypeExample"></a>example | [Example Object](#exampleObject) | Example of the content type.
+<a name="contentTypeExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the content type.  Each example in the Examples Array must be in the correct format as specified in the _content_ type.  The `examples` object is mutually exclusive to the `example` object.  Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema.
+<a name="contentTypeExample"></a>example | [Example Object](#exampleObject) | Example of the content type.  The example object _must_ be in the correct format as specified in the _content_ type.  The `example` object is mutually exclusive to the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the the example provided by the schema.


I thought on the call Ron suggested softening the MUST to a SHOULD. (in the above para, use MUST not must as per rfc)

DavidBiesack · 2017-02-21T20:57:24Z

versions/3.0.md

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


... more weight to using SHOULD instead of MUSt above.

Examples documentation Merging per @OAI/tdc call

fehguy added 3 commits February 16, 2017 14:48

Merge branch 'OpenAPI.next' of github.com:OAI/OpenAPI-Specification i…

810b46a

…nto issue-589-responses

Merge branch 'OpenAPI.next' of github.com:OAI/OpenAPI-Specification i…

bd50a94

…nto issue-589-responses

added clarification for examples

5d93c54

fehguy commented Feb 20, 2017

View reviewed changes

fehguy mentioned this pull request Feb 20, 2017

[Meta Issue] Specification documentation structure and supporting docs #589

Closed

fixed zip example

3ec85a2

fehguy commented Feb 21, 2017

View reviewed changes

fixes per @OAI/TDC discussion

d162497

DavidBiesack reviewed Feb 21, 2017

View reviewed changes

updated must ~~> should per @OAI/tdc

283006c

fehguy merged commit 1a0248c into OpenAPI.next Feb 22, 2017

fehguy deleted the issue-589-examples branch February 22, 2017 17:29

AndersDJohnson pushed a commit to AndersDJohnson/OpenAPI-Specification that referenced this pull request Apr 8, 2019

Merge pull request OAI#893 from OAI/issue-589-examples

e9b31f2

Examples documentation Merging per @OAI/tdc call

handrews mentioned this pull request Jun 9, 2024

Consolidate guidance around examples (3.0.4) #3893

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Examples documentation #893

Examples documentation #893

fehguy commented Feb 20, 2017

fehguy Feb 20, 2017

handrews Feb 21, 2017

darrelmiller Feb 21, 2017

fehguy Feb 21, 2017

fehguy Feb 20, 2017

DavidBiesack Feb 21, 2017

fehguy Feb 20, 2017

fehguy Feb 21, 2017

earth2marsh Feb 21, 2017

whitlockjc commented Feb 21, 2017

darrelmiller commented Feb 21, 2017

webron commented Feb 21, 2017

whitlockjc commented Feb 21, 2017

DavidBiesack Feb 21, 2017

DavidBiesack Feb 21, 2017


		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.

Examples documentation #893

Examples documentation #893

Conversation

fehguy commented Feb 20, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whitlockjc commented Feb 21, 2017

darrelmiller commented Feb 21, 2017

webron commented Feb 21, 2017

whitlockjc commented Feb 21, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment