From 6c21f32d46606d90d96259ad3ab2765885c0d892 Mon Sep 17 00:00:00 2001
From: Tony Tam <fehguy@gmail.com>
Date: Fri, 8 Apr 2016 06:22:01 -0700
Subject: [PATCH 1/2] adde examples object

---
 versions/3.0.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/versions/3.0.md b/versions/3.0.md
index 1d6a2d02a9..bd9e584c35 100644
--- a/versions/3.0.md
+++ b/versions/3.0.md
@@ -1152,6 +1152,51 @@ name: pet
 description: Pets operations
 ```
 
+#### <a name="examplesObject"></a>Examples Object
+
+Anywhere an `example` may be given, allow a $ref object.  This does mean that `example` can be either a string primitive or an object, like `additionalProperties`:
+
+```yaml
+# in a model
+definitions:
+  properties:
+    name:
+      type: string
+      example:
+        $ref: http://foo.bar#/examples/name-example.json
+
+# in a parameter:
+  parameters:
+    - name: address
+      in: body
+      schema:
+        $ref: '#/definitions/Address'
+      examples:
+        'application/json':
+          $ref: http://foo.bar#/examples/address-example.json
+        'application/xml':
+          $ref: http://foo.bar#/examples/address-example.xml
+        'text/plain':
+          $ref: http://foo.bar#/examples/address-example.txt
+        default:
+          $ref: http://foo.bar#/examples/address-example.whatever
+    - name: zip
+      in: query
+      type: string
+      format: zip
+      example: 
+        $ref: http://foo.bar#/examples/zip-example
+# in a response:
+  responses:
+    200:
+      description: your car appointment has been booked
+        schema:
+          $ref: '#/definitions/SuccessResponse'
+      examples:
+        'application/json':
+          $ref: http://foo.bar#/examples/address-example.json
+```
+
 #### <a name="referenceObject"></a>Reference Object
 
 A simple object to allow referencing other definitions in the specification. It can be used to reference parameters and responses that are defined at the top level for reuse.

From 6bb80f81366f9d94b3cba662843943747e815def Mon Sep 17 00:00:00 2001
From: Tony Tam <fehguy@gmail.com>
Date: Mon, 11 Apr 2016 13:55:36 -0700
Subject: [PATCH 2/2] clarifications

---
 versions/3.0.md | 34 +++++++++++++++++++---------------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/versions/3.0.md b/versions/3.0.md
index bd9e584c35..6eb185443b 100644
--- a/versions/3.0.md
+++ b/versions/3.0.md
@@ -1154,7 +1154,11 @@ description: Pets operations
 
 #### <a name="examplesObject"></a>Examples Object
 
-Anywhere an `example` may be given, allow a $ref object.  This does mean that `example` can be either a string primitive or an object, like `additionalProperties`:
+Anywhere an `example` may be given, allow a $ref object.  This does mean that `example`, structurally, can be either a string primitive or an object, like `additionalProperties`.
+
+In locations where the field being provided an `example` is a scalar value _or_ has it's content-type definition determined by a higher-level construct (a response payload, for example, uses the `produces` attribute to select the correct message format), the plural `examples` shall be used, and the payload format be specified as a key to the example.
+
+In all cases, the payload is expected to be compatible with the type schema for the value that it is accompanying. Tooling vendors may choose to valide compatibility automatically, and reject the example value(s) if they are not compatible.
 
 ```yaml
 # in a model
@@ -1163,9 +1167,9 @@ definitions:
     name:
       type: string
       example:
-        $ref: http://foo.bar#/examples/name-example.json
+        $ref: http://foo.bar#/examples/name-example
 
-# in a parameter:
+# in a parameter, note the plural `examples` as the content-type is set by `consumes`:
   parameters:
     - name: address
       in: body
@@ -1173,25 +1177,25 @@ definitions:
         $ref: '#/definitions/Address'
       examples:
         'application/json':
-          $ref: http://foo.bar#/examples/address-example.json
+          $ref: 'http://foo.bar#/examples/address-example.json'
         'application/xml':
-          $ref: http://foo.bar#/examples/address-example.xml
+          $ref: 'http://foo.bar#/examples/address-example.xml'
         'text/plain':
-          $ref: http://foo.bar#/examples/address-example.txt
+          $ref: 'http://foo.bar#/examples/address-example.txt'
         default:
-          $ref: http://foo.bar#/examples/address-example.whatever
-    - name: zip
-      in: query
-      type: string
-      format: zip
+          $ref: 'http://foo.bar#/examples/address-example.whatever'
+    - name: 'zip'
+      in: 'query'
+      type: 'string'
+      format: 'zip'
       example: 
-        $ref: http://foo.bar#/examples/zip-example
-# in a response:
+        $ref: 'http://foo.bar#/examples/zip-example'
+# in a response, note the plural `examples`:
   responses:
     200:
       description: your car appointment has been booked
-        schema:
-          $ref: '#/definitions/SuccessResponse'
+      schema:
+        $ref: '#/definitions/SuccessResponse'
       examples:
         'application/json':
           $ref: http://foo.bar#/examples/address-example.json