Updates based on PR Comments

Author: darrelmiller

versions/3.0.md

@@ -937,7 +937,7 @@ 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) \| [Reference Object](#referenceObject)] | The schema defining the type used for the parameter.
-<a name="parameterExample"></a>example | Any | Example of the media 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 the example provided by the schema. To represent examples of media types that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
+<a name="parameterExample"></a>example | Any | Example of the media type.  The example SHOULD match the specified schema and encoding properties if present.  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. To represent examples of media types that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
 <a name="parameterExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example SHOULD contain a value in the correct format as specified in the 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.
 
 For more complex scenarios a [Content Object](#contentObject) can be used to define the media type 
@@ -1324,7 +1324,7 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body.
 <a name="mediaTypeExample"></a>example | Any | Example of the media type.  The example object SHOULD be in the correct format as specified in the media 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.
-<a name="mediaTypeExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example object SHOULD contain a value in the correct format as specified in the media 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="mediaTypeExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example object SHOULD  match the media type and specified schema if present.  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="mediaTypeEncoding"></a>encoding | [Encoding Object](#encodingObject) | Encoding of the media type.  The encoding object SHOULD only apply to `requestBody` objects when the content type is `multipart`.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
@@ -1343,14 +1343,23 @@ This object can be extended with [Specification Extensions](#specificationExtens
         "value": 
           {
             "name": "Fluffy",
-            "petType": "Cat"
+            "petType": "Cat",
+            "color": "White",
+            "gender": "male",
+            "breed": "Persian"
           }
       },
-      "frog": {
-        "summary": "An example of a frog with a dog's name",
+      "dog": {
+        "summary": "An example of a dog with a cat's name",
         "value" :  { 
-          "name": "Rover",
-          "petType": "Frog"
+          "name": "Puma",
+          "petType": "Dog",
+          "color": "Black",
+          "gender": "Female",
+          "breed": "Mixed"
+        },
+      "frog": {
+          "$ref": "#/components/examples/frog-example"
         }
       }
     }
@@ -1368,13 +1377,19 @@ application/json:
       value:
         name: Fluffy
         petType: Cat
-    frog:
-      summary: An example of a frog with a dog's name
-      value:
-        name: Rover
-        petType: Frog
+        color: White
+        gender: male
+        breed: Persian
     dog:
-      $ref: "#/components/examples/dog-example"
+      summary: An example of a dog with a cat's name
+      value:
+        name: Puma
+        petType: Dog
+        color: Black
+        gender: Female
+        breed: Mixed
+    frog:
+      $ref: "#/components/examples/frog-example"
 ```
 
 ##### Considerations for file uploads
@@ -1918,9 +1933,9 @@ schemas:
       type: string
       examples:
         name:
-          $ref: http://example.org/petapi-examples/OpenApi.json#/components/examples/name-example
+          $ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example
 
-# in a request body, note the plural `examples` as the Content-Type is set to `*`:
+# in a request body:
   requestBody:
     content:
       'application/json':
@@ -2532,7 +2547,6 @@ schemas:
             $ref: http://foo.bar#/examples/address-example.json
 ```
 
->>>>>>> refs/remotes/origin/OpenAPI.next
 #### <a name="referenceObject"></a>Reference Object
 
 A simple object to allow referencing other components in the specification, internally and externally.
@@ -2792,65 +2806,6 @@ example:
   id: 1
 ```
 
-###### Model with Examples
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "id": {
-      "type": "integer",
-      "format": "int64"
-    },
-    "name": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "name"
-  ],
-  "examples": {
-    "cat": {
-      "summary": "Big cat example",
-      "value": {
-        "name": "Puma",
-        "id": 1
-      }
-    },
-    "dog": {
-      "summary": "Family dog example",
-      "value": {
-        "name": "Ferguson",
-        "id": 2
-      }
-    }
-  }
-}
-```
-
-```yaml
-type: object
-properties:
-  id:
-    type: integer
-    format: int64
-  name:
-    type: string
-required:
-- name
-examples:
-  cat:
-    summary: Big cat example
-    value:
-      name: Puma
-      id: 1
-  dog:
-    summary: Family Dog
-    value:
-      name: Ferguson
-      id: 2
-```
-
 ###### Models with Composition
 
 ```json