Merge pull request OAI#636 from OAI/issue-544

Add examples object

[Manually ported merge]

Co-authored-by: Tony Tam <tony@eatbacon.org>

Author: handrews

Diff for: dev/oas.md

@@ -1163,6 +1163,55 @@ 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`, 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
+definitions:
+  properties:
+    name:
+      type: string
+      example:
+        $ref: http://foo.bar#/examples/name-example
+
+# in a parameter, note the plural `examples` as the content-type is set by `consumes`:
+  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, note the plural `examples`:
+  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.