Update examplesObject

Clarify that Examples Object may be used instead of Example Object.

Show JSON examples as well as YAML

Clarify the $ref values used in examples to remove ambiguity.
These are not references to external JSON/XML/TXT resources, but
rather are references to reusable examples in the current OpenAPI definition
or in an external OpenAPI definition's components/examples

This does not yet address issue OAI#488 but cleans up Examples Object
a bit, which is needed whether we alter the OAS as per OAI#488 .

Author: David Biesack

versions/3.0.md

@@ -1128,20 +1128,20 @@ A request body with a referenced model definition.
       "schema": {
         "$ref": "#/components/schemas/User"
       },
-      "examples": [ "http://foo.bar/examples/user-example.json" ]
+      "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.json" ]
     },
     "application/xml": {
       "schema": {
         "$ref": "#/components/schemas/User"
       },
-      "examples": [ "http://foo.bar/examples/user-example.xml" ]
+      "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.xml" ]
     },
     "text/plain": {
-      "examples": [ "http://foo.bar/examples/user-example.txt" ]
+      "examples": [ "http://foo.bar/other-api.yaml#/components/examples/user-example.txt" ]
     },
     "*/*": {
       "example": {
-        "$ref": "http://foo.bar/examples/user-example.whatever"
+        "$ref": "http://foo.bar/other-api.yaml#/components/examples/user-example.whatever"
       }
     }
   }
@@ -1155,18 +1155,18 @@ content:
     schema:
       $ref: '#/components/schemas/User'
     examples:
-      - 'http://foo.bar/examples/user-example.json'
+      - 'http://foo.bar/other-api.yaml#/components/examples/user-example.json'
   'application/xml':
     schema:
       $ref: '#/components/schemas/User'
     examples:
-      - 'http://foo.bar/examples/user-example.xml'
+      - 'http://foo.bar/other-api.yaml#/components/examples/user-example.xml'
   'text/plain':
     examples:
-      - 'http://foo.bar/examples/user-example.txt'
+      - 'http://foo.bar/other-api.yaml#/components/examples/user-example.txt'
   '*/*':
     example:
-      $ref: 'http://foo.bar/examples/user-example.whatever'
+      $ref: 'http://foo.bar/other-api.yaml#/components/examples/user-example.whatever'
 ```
 
 A body parameter that is an array of string values:
@@ -2355,7 +2355,12 @@ description: Pets operations
 
 #### <a name="examplesObject"></a>Examples Object
 
-Anywhere an `example` may be given, a JSON Reference MAY be used, with the 
+Instead of a single `example`, you may provide an array of 
+[Example Object](#exampleObject) values named `examples'.
+`example` and `examples` are mutually exclusive.
+
+Anywhere an `example` may be given (including in the Examples Object array), 
+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`.
@@ -2365,42 +2370,133 @@ 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.
 
+Here is a single `example` in a model [Schema Object](#schemaObject):
+
+```json
+  "components" : {
+    "schemas" : {
+      "identity" : {
+        "properties" : {
+          "name" : {
+            "type" : "string"
+          }
+        },
+        "example" : {
+          "$ref" : "#/components/examples/identity"
+        }
+      }
+    }
+```
+}
+
 ```yaml
-# in a model
-schemas:
-  properties:
-    name:
-      type: string
+components:
+  schemas:
+    identity:
+      properties:
+        name:
+          type: string
       example:
-        $ref: http://foo.bar#/examples/name-example
+        $ref: "#/components/examples/identity"
+```
 
-# in a request body, note the plural `examples` as the Content-Type is set to `*`:
+Below is an `examples` array in a [Request Body Object](#requestBodyObject),
+showing two in-line examples and references
+to examples in the document's [Components Object](#componentsObject):
+
+```json
+  "requestBody" : {
+    "content" : {
+      "application/json" : {
+        "schema" : {
+          "$ref" : "#/components/schemas/Address"
+        },
+        "examples" : [ {
+          "street" : "119 N Weatherly Ave.",
+          "zip" : "55405"
+        }, {
+          "street" : "119 N Weatherly Ave",
+          "street2" : "Apt. D",
+          "city" : "Minneapolis",
+          "state" : "MN",
+          "zip" : "55405",
+          "type" : "residence"
+        }, {
+          "$ref" : "#/components/examples/alt-address"
+        } ]
+      },
+      "application/xml" : {
+        "examples" : [ {
+          "$ref" : "#/components/examples/simple-address.xml"
+        }, {
+          "$ref" : "#/components/examples/complete-address.xml"
+        } ]
+      },
+      "text/plain" : {
+        "examples" : [ {
+          "$ref" : "#/components/examples/address-example.txt"
+        } ]
+      }
+    }
+  }
+```
+
+```yaml
   requestBody:
     content:
       'application/json':
         schema:
           $ref: '#/components/schemas/Address'
         examples: 
-          - {"foo": "bar"}
-          - {"bar": "baz"}
+          - { "street": "119 N Weatherly Ave.", "zip" : "55405" }
+          - street: 119 N Weatherly Ave
+            street2: Apt. D
+            city: Minneapolis
+            state: MN
+            zip : '55405'
+            type: residence
+          - $ref: '#/components/examples/alt-address'
       'application/xml':
         examples: 
-          - $ref: 'http://foo.bar#/examples/address-example.xml' 
+          - $ref: '#/components/examples/simple-address.xml' 
+          - $ref: '#/components/examples/complete-address.xml' 
       'text/plain':
         examples: 
-          - $ref: 'http://foo.bar#/examples/address-example.txt' 
-        
-# in a parameter
-
+          - $ref: '#/components/examples/address-example.txt' 
+```        
+This shows referencing an example component from another OpenAPI definition,
+in a [Parameter Object](#parameterObject):
+```yaml
   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`:
+          $ref: 'http://foo.bar/other-api.yaml#/components/examples/zip-example'
+```
+
+Finally, in a [Response Object](#responseObject):
+
+```json
+  "responses" : {
+    "200" : {
+      "description" : "your car appointment has been booked",
+      "content" : {
+        "application/json" : {
+          "schema" : {
+            "$ref" : "#/components/schemas/SuccessResponse"
+          },
+          "example" : {
+            "$ref" : "http://foo.bar/other-api.yaml#/components/examples/address-example.json"
+          }
+        }
+      }
+    }
+}```
+
+```yaml
   responses:
     '200':
       description: your car appointment has been booked
@@ -2409,7 +2505,7 @@ schemas:
           schema:
             $ref: '#/components/schemas/SuccessResponse'
           example:
-            $ref: http://foo.bar#/examples/address-example.json
+            $ref: http://foo.bar/other-api.yaml#/components/examples/address-example.json
 ```
 
 #### <a name="referenceObject"></a>Reference Object