Merge pull request #907 from OAI/dm/issue-906

Fixes for Example object #906

Author: webron

versions/3.0.md

@@ -761,8 +761,8 @@ Field Name | Type | Description
 <a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map.  For other types of parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, 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.
+<a name="parameterExamples"></a>examples | [[Example Object](#exampleObject)] | Examples of the content type.  Each example in the Examples array SHOULD 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 SHALL _override_ the example provided by the schema.
+<a name="parameterExample"></a>example | [Example Object](#exampleObject) | Example of the content type.  The example object SHOULD 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 SHALL _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.  This option is mutually exclusive with the simple scenario
@@ -1089,8 +1089,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.  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.
+<a name="contentTypeExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the content type.  Each example in the Examples array SHOULD 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 SHALL _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 SHALL _override_ the the example provided by the schema.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
@@ -1642,38 +1642,32 @@ X-Rate-Limit-Reset:
     type: integer
 ```
 
-#### <a name="examplesObject"></a>Examples Object
-
-Allows sharing examples for operation requests and responses.
+#### <a name="exampleObject"></a>Example Object
 
-##### Patterned Fields
-Field Pattern | Type | Description
----|:---:|---
-<a name="exampleMediaType"></a>{[media type](#mediaTypes)} | Any | 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. 
+Allows sharing examples for operation requests and responses. This object can either be a freeform object, array or primitive value.  To represent examples of media types that cannot naturally represented in the OpenAPI definition, a string value can be used to contain the example with escaping where necessary. 
 
-##### Examples Array Example
+##### Example Example
 
 Example representation for application/json media type of a Pet data type:
 
 ```json
-[
   {
     "name": "Puma",
     "type": "Dog",
     "color": "Black",
     "gender": "Female",
     "breed": "Mixed"
   }
-]
 ```
 
 ```yaml
--
-  name: Puma
-  type: Dog
-  color: Black
-  gender: Female
-  breed: Mixed
+
+name: Puma
+type: Dog
+color: Black
+gender: Female
+breed: Mixed
+
 ```
 
 #### <a name="linksObject"></a>Links Object