Updates based on review

darrelmiller · darrelmiller · commit c0943807468f · 2017-04-15T20:24:09.000-04:00
diff --git a/versions/3.0.md b/versions/3.0.md
@@ -53,7 +53,6 @@ Additional utilities can also take advantage of the resulting files, such as tes
 		- [Callback Object](#callbackObject)
 		- [Headers Object](#headersObject)
 		- [Example Object](#exampleObject)
-		- [Described Example Object](#describedExampleObject)
 		- [Links Object](#linksObject)
 		- [Link Object](#linkObject)
 		- [Link Parameters Object](#linkParametersObject)
@@ -408,7 +407,7 @@ Field Name | Type | Description
 <a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable [Schema Objects](#schemaObject).
 <a name="componentsResponses"></a> responses | Map[`string`, [Response Object](#responseObject)] | An object to hold reusable [Response Objects](#responseObject).
 <a name="componentsParameters"></a> parameters | Map[`string`, [Parameter Object](#parameterObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
-<a name="componentsExamples"></a> examples | Map[`string`, [Described Example Object](#describedExampleObject)] | An object to hold reusable [Described Example Objects](#describedExampleObject).
+<a name="componentsExamples"></a> examples | Map[`string`, [Example Object](#exampleObject)] | An object to hold reusable [Example Objects](#exampleObject).
 <a name="componentsRequestBodies"></a> requestBodies | Map[`string`, [Request Body Object](#requestBodyObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject).
 <a name="componentsHeaders"></a> headers | Map[`string`, [Header object](#headerObject)] | An object to hold reusable [Header objects](#headerObject).
 <a name="componentsSecuritySchemes"></a> securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
@@ -938,8 +937,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) \| [Reference Object](#referenceObject)] | The schema defining the type used for the parameter.
-<a name="parameterExample"></a>example | [Example Object](#exampleObject) | 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.
-<a name="parameterExamples"></a>examples | Map[ `string`, [Described Example Object](#describedExampleObject) \| [Reference Object](#referenceObject)] | Described Examples of the media type.  Each described 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.
+<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="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 
 and schema of the parameter.  This option is mutually exclusive with the simple scenario
@@ -1131,7 +1130,7 @@ A request body with a referenced model definition.
       "examples": {
           "user" : {
             "summary": "User Example", 
-            "valueUrl": "http://foo.bar/examples/user-example.json"
+            "externalValue": "http://foo.bar/examples/user-example.json"
           } 
         }
     },
@@ -1142,23 +1141,23 @@ A request body with a referenced model definition.
       "examples": {
           "user" : {
             "summary": "User example in XML",
-            "valueUrl": "http://foo.bar/examples/user-example.xml"
+            "externalValue": "http://foo.bar/examples/user-example.xml"
           }
         }
     },
     "text/plain": {
       "examples": {
         "user" : {
             "summary": "User example in Plain text",
-            "valueUrl": "http://foo.bar/examples/user-example.txt" 
+            "externalValue": "http://foo.bar/examples/user-example.txt" 
         }
       } 
     },
     "*/*": {
       "examples": {
         "user" : {
             "summary": "User example in other format",
-            "valueUrl": "http://foo.bar/examples/user-example.whatever"
+            "externalValue": "http://foo.bar/examples/user-example.whatever"
         }
       }
     }
@@ -1175,24 +1174,24 @@ content:
     examples:
       user:
         summary: User Example
-        valueUrl: 'http://foo.bar/examples/user-example.json'
+        externalValue: 'http://foo.bar/examples/user-example.json'
   'application/xml':
     schema:
       $ref: '#/components/schemas/User'
     examples:
       user:
         summary: User Example in XML
-        valueUrl: 'http://foo.bar/examples/user-example.xml'
+        externalValue: 'http://foo.bar/examples/user-example.xml'
   'text/plain':
     examples:
       user:
         summary: User example in text plain format
-        valueUrl: 'http://foo.bar/examples/user-example.txt'
+        externalValue: 'http://foo.bar/examples/user-example.txt'
   '*/*':
     examples:
       user: 
         summary: User example in other format
-        valueUrl: 'http://foo.bar/examples/user-example.whatever'
+        externalValue: 'http://foo.bar/examples/user-example.whatever'
 ```
 
 A body parameter that is an array of string values:
@@ -1324,8 +1323,8 @@ Each Media Type Object provides schema and examples for a the media type identif
 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 | [Example Object](#exampleObject) | 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`, [Described Example Object](#describedExampleObject) \| [Reference Object](#referenceObject)] | Described Examples of the media type.  Each described example 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="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="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). 
@@ -1894,41 +1893,13 @@ X-Rate-Limit-Reset:
 
 #### <a name="exampleObject"></a>Example Object
 
-Allows sharing examples for operation requests and responses. This literal value can either be any JSON or YAML 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. 
-
-##### Example Object 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
-
-```
-
-#### <a name="describedExampleObject"></a>Described Example Object
-
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-<a name="describedExampleSummary"></a>summary | `string` | Short description for the example.
-<a name="describedExampleDescription"></a>description | `string` | Long description for the example.
-<a name="describedExampleValue"></a>value | [Example Object](#exampleObject) | Embedded literal example. The `value` field and `valueUrl` field are mutually exclusive.
-<a name="describedExampleValueUrl"></a>valueUrl | `string` | A URL that points to the literal example. This provides the ability to reference examples that cannot easily be included in JSON or YAML documents.  The `value` field and `valueUrl` field are mutually exclusive. 
+<a name="exampleSummary"></a>summary | `string` | Short description for the example.
+<a name="exampleDescription"></a>description | `string` | Long description for the example.
+<a name="exampleValue"></a>value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. 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="exampleExternalValue"></a>externalValue | `string` | A URL that points to the literal example. This provides the ability to reference examples that cannot easily be included in JSON or YAML documents.  The `value` field and `externalValue` field are mutually exclusive. 
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
@@ -1937,7 +1908,7 @@ 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.
 
-##### Described Example Object Example
+##### Example Object Example
 
 ```yaml
 # in a model
@@ -1966,12 +1937,12 @@ schemas:
         examples: 
           xmlExample:
             summary: This is an example in XML
-            valueUrl: 'http://example.org/examples/address-example.xml'
+            externalValue: 'http://example.org/examples/address-example.xml'
       'text/plain':
         examples:
           textExample: 
             summary: This is a text example
-            valueUrl: 'http://foo.bar/examples/address-example.txt' 
+            externalValue: 'http://foo.bar/examples/address-example.txt' 
 
 
 # in a parameter
@@ -2667,7 +2638,7 @@ Field Name | Type | Description
 <a name="schemaWriteOnly"></a>writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". This means that it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`.
 <a name="schemaXml"></a>xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property.
 <a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 
-<a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema.
+<a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
 <a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
