First attempt at described example

darrelmiller · darrelmiller · commit 8d3dc3f6d391 · 2017-04-07T11:49:34.000-07:00
diff --git a/versions/3.0.md b/versions/3.0.md
@@ -49,12 +49,12 @@ Additional utilities can also take advantage of the resulting files, such as tes
 		- [Response Object](#responseObject)
 		- [Headers Object](#headersObject)
 		- [Example Object](#exampleObject)
+		- [Described Example Object](#describedExampleObject)
 		- [Links Object](#linksObject)
 		- [Link Object](#linkObject)
 		- [Link Parameters Object](#linkParametersObject)
 		- [Header Object](#headerObject)
 		- [Tag Object](#tagObject)
-		- [Examples Object](#examplesObject)
 		- [Reference Object](#referenceObject)
 		- [Schema Object](#schemaObject)
 		- [XML Object](#xmlObject)
@@ -402,7 +402,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`, [Example Object](#exampleObject)] | An object to hold reusable [Example Objects](#exampleObject).
+<a name="componentsExamples"></a> examples | Map[`string`, [Described Example Object](#describedExampleObject)] | An object to hold reusable [Described Example Objects](#describedExampleObject).
 <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).
@@ -932,8 +932,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) <span>&#124;</span> [Reference Object](#referenceObject)] | The schema defining the type used for the parameter.
-<a name="parameterExamples"></a>examples | [[Example Object](#exampleObject) <span>&#124;</span> [Reference Object](#referenceObject)] | 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) <span>&#124;</span> [Reference Object](#referenceObject) | 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.
+<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) <span>&#124;</span> [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.
 
 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
@@ -1258,9 +1258,9 @@ Each Media Type Object provides schema and examples for a the media type identif
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-<a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The schema defining the type used for the request body.
-<a name="mediaTypeExamples"></a>examples | [[Example Object](#exampleObject) <span>&#124;</span> [Reference Object](#referenceObject)] | Examples of the media type.  Each example in the Examples array SHOULD be 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 | [Example Object](#exampleObject) <span>&#124;</span> [Reference Object](#referenceObject) | 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="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) <span>&#124;</span> [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) <span>&#124;</span> [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="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). 
@@ -1273,14 +1273,23 @@ This object can be extended with [Specification Extensions](#specificationExtens
     "schema": {
          "$ref": "#/components/schemas/Pet"
     },
-    "examples": [{
-                  "name": "Fluffy",
-                  "petType": "Cat"
-                 },
-                 { 
-                   "name": "Rover",
-                   "petType": "Frog"
-                 }]
+    "examples": {
+      "cat" : {
+        "summary": "An example of a cat",
+        "value": 
+          {
+            "name": "Fluffy",
+            "petType": "Cat"
+          }
+      },
+      "frog": {
+        "summary": "An example of a frog with a dog's name",
+        "value" :  { 
+          "name": "Rover",
+          "petType": "Frog"
+        }
+      }
+    }
   }
 }
 ```
@@ -1290,11 +1299,18 @@ application/json:
   schema:
     $ref: "#/components/schemas/Pet"
   examples:
-    # converted directly from YAML to JSON
-    - name: Fluffy
-      petType: Cat
-    - {"name": "Rover", "petType": "Frog"}
-
+    cat:
+      summary: An example of a cat
+      value:
+        name: Fluffy
+        petType: Cat
+    frog:
+      summary: An example of a frog with a dog's name
+      value:
+        name: Rover
+        petType: Frog
+    dog:
+      $ref: "#/components/examples/dog-example"
 ```
 
 ##### Considerations for file uploads
@@ -1813,7 +1829,7 @@ X-Rate-Limit-Reset:
 
 #### <a name="exampleObject"></a>Example Object
 
-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. 
+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 Example
 
@@ -1839,6 +1855,82 @@ 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. 
+
+This object can be extended with [Specification Extensions](#specificationExtensions). 
+
+In all cases, the example value 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.
+
+##### Example Described Example
+
+```yaml
+# in a model
+schemas:
+  properties:
+    name:
+      type: string
+      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 `*`:
+  requestBody:
+    content:
+      'application/json':
+        schema:
+          $ref: '#/components/schemas/Address'
+        examples: 
+          foo:
+            summary: A foo example
+            value: {"foo": "bar"}
+          bar:
+            summary: A bar example
+            value: {"bar": "baz"}
+      'application/xml':
+        examples: 
+          xmlExample:
+            summary: This is an example in XML
+            valueUrl: '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' 
+        
+# in a parameter
+  parameters:
+    - name: 'zipCode'
+      in: 'query'
+      schema:
+        type: 'string'
+        format: 'zip-code'
+        examples:
+          zip-example: 
+            $ref: '#/components/examples/zip-example'
+
+# in a response
+  responses:
+    200:
+      description: your car appointment has been booked
+      content: 
+        application/json:
+          schema:
+            $ref: '#/components/schemas/SuccessResponse'
+          examples:
+            confirmation-success:
+              $ref: '#/components/examples/confirmation-success'
+```
+
 #### <a name="linksObject"></a>Links Object
 The links object represents a set of possible design-time links for a response.
 The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.
@@ -2344,64 +2436,6 @@ name: pet
 description: Pets operations
 ```
 
-#### <a name="examplesObject"></a>Examples Object
-
-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 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
-schemas:
-  properties:
-    name:
-      type: string
-      example:
-        $ref: http://foo.bar#/examples/name-example
-
-# in a request body, note the plural `examples` as the Content-Type is set to `*`:
-  requestBody:
-    content:
-      'application/json':
-        schema:
-          $ref: '#/components/schemas/Address'
-        examples: 
-          - {"foo": "bar"}
-          - {"bar": "baz"}
-      'application/xml':
-        examples: 
-          - $ref: 'http://foo.bar#/examples/address-example.xml' 
-      'text/plain':
-        examples: 
-          - $ref: 'http://foo.bar#/examples/address-example.txt' 
-        
-# in a parameter
-
-  parameters:
-    - name: 'zipCode'
-      in: 'query'
-      schema:
-        type: 'string'
-        format: 'zip-code'
-        example: 
-          $ref: 'http://foo.bar#/examples/zip-example'
-# in a response, note the plural `examples`:
-  responses:
-    200:
-      description: your car appointment has been booked
-      content: 
-        application/json:
-          schema:
-            $ref: '#/components/schemas/SuccessResponse'
-          example:
-            $ref: http://foo.bar#/examples/address-example.json
-```
 
 #### <a name="referenceObject"></a>Reference Object
 
@@ -2509,7 +2543,6 @@ Field Name | Type | Description
 <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="schemaExamples"></a>examples | Any | An array of free-formed properties to include examples for this schema.
 <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). 
