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

Examples documentation Merging per @OAI/tdc call

Author: fehguy

versions/3.0.md

@@ -764,8 +764,13 @@ Field Name | Type | Description
 <a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map.  For other types of parameters this property has no effect. The default value is false.
 <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.
+<a name="parameterExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the content type.  Each example in the Examples Array must be in the correct format as specified parameter encoding.  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="parameterExample"></a>example | [Example Object](#exampleObject) | Example of the content type.  The example object _must_ be in the correct format as specified in the parameter encoding.  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 example provided by the the schema.
 
-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.  This option is mutually exclusive with the simple scenario
+above. When `example` or `examples` are provided in conjunction with the `schema` object, 
+the example must follow the prescribed serialization strategy for the parameter.
 
 Field Name | Type | Description
 ---|:---:|---
@@ -1062,8 +1067,8 @@ Each content type object provides schema and examples for a the media type ident
 Field Name | Type | Description
 ---|:---:|---
 <a name="contentTypeSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
-<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 _should_ 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.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
@@ -1096,10 +1101,10 @@ application/json:
   schema:
     $ref: "#/definitions/Pet"
   examples:
+    # converted directly from YAML to JSON
     - name: Fluffy
       petType: Cat
-    - name: Rover
-      petType: Frog
+    - {"name": "Rover", "petType": "Frog"}
 
 ```
 
@@ -2077,13 +2082,15 @@ description: Pets operations
 
 #### <a name="examplesObject"></a>Examples Object
 
-Anywhere an `example` may be given, allow a $ref object.
-This does mean that `example`, structurally, can be either a string primitive or an object, like `additionalProperties`.
+Anywhere an `example` may be given, a JSON Reference may be used, with the 
+explicit restriction that examples having a JSON format with object named 
+`$ref` are not allowed. This does mean that `example`, structurally, can be 
+either a string primitive or an object, similar to `additionalProperties`.
 
-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 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 
+validate compatibility automatically, and reject the example value(s) if they 
+are not compatible.
 
 ```yaml
 # in a model
@@ -2105,22 +2112,21 @@ definitions:
           - {"bar": "baz"}
       'application/xml':
         examples: 
-          -   
-            $ref: 'http://foo.bar#/examples/address-example.xml' 
+          - $ref: 'http://foo.bar#/examples/address-example.xml' 
       'text/plain':
         examples: 
-          -
-            $ref: 'http://foo.bar#/examples/address-example.txt' 
+          - $ref: 'http://foo.bar#/examples/address-example.txt' 
 
 # in a parameter
 
   parameters:
-    - name: 'zip'
+    - name: 'zipCode'
       in: 'query'
-      type: 'string'
-      format: 'zip'
-      example: 
-        $ref: 'http://foo.bar#/examples/zip-example'
+      schema:
+        type: 'string'
+        format: 'zip-code'
+        example: 
+          $ref: 'http://foo.bar#/examples/zip-example'
 # in a response, note the plural `examples`:
   responses:
     200: