From 0bc56933fecf9179bde7873403bdca6e68cbddd6 Mon Sep 17 00:00:00 2001
From: Darrel <darrel@tavis.ca>
Date: Tue, 9 Aug 2016 16:31:11 -0400
Subject: [PATCH 1/6] Initial changes

---
 versions/3.0.md | 323 +++++++++++++++++++++++++++++++-----------------
 1 file changed, 210 insertions(+), 113 deletions(-)

diff --git a/versions/3.0.md b/versions/3.0.md
index 96c7814515..15b47c2755 100644
--- a/versions/3.0.md
+++ b/versions/3.0.md
@@ -114,9 +114,7 @@ Field Name | Type | Description
 <a name="oasVersion"></a>openapi | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version.  The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document.
 <a name="oasInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed.
 <a name="oasHosts"></a>hosts | [Hosts Object](#hostsObject) | An array of Host objects which provide `scheme`, `host`, `port`, and `basePath` in an associative manner.
-<a name="oasConsumes"></a>consumes | [`string`] | A list of media types the APIs can consume. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Media Types](#mediaTypes).
-<a name="oasProduces"></a>produces | [`string`] | A list of media types the APIs can produce. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Media Types](#mediaTypes).
-<a name="oasResponses"></a>responses | [Responses]
+<a name="oasResponses"></a>responses | [Responses](#responsesObject)
 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API.
 <a name="oasSchemas"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
 <a name="oasSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition.
@@ -295,16 +293,17 @@ Field Pattern | Type | Description
   "/pets": {
     "get": {
       "description": "Returns all pets from the system that the user has access to",
-      "produces": [
-        "application/json"
-      ],
       "responses": {
-        "200": {
+        "200": {          
           "description": "A list of pets.",
-          "schema": {
-            "type": "array",
-            "items": {
-              "$ref": "#/definitions/pet"
+          "representations" : {
+            "application/json" : {
+                "schema": {
+                            "type": "array",
+                            "items": {
+                              "$ref": "#/definitions/pet"
+                            }
+                          }
             }
           }
         }
@@ -318,15 +317,15 @@ Field Pattern | Type | Description
 /pets:
   get:
     description: Returns all pets from the system that the user has access to
-    produces:
-    - application/json
     responses:
       '200':
         description: A list of pets.
-        schema:
-          type: array
-          items:
-            $ref: '#/definitions/pet'
+        representations:
+          'application/json':
+            schema:
+              type: array
+              items:
+                $ref: '#/definitions/pet'
 ```
 
 #### <a name="pathItemObject"></a>Path Item Object
@@ -367,24 +366,28 @@ Field Pattern | Type | Description
     "description": "Returns pets based on ID",
     "summary": "Find pets by ID",
     "operationId": "getPetsById",
-    "produces": [
-      "application/json",
-      "text/html"
-    ],
     "responses": {
       "200": {
         "description": "pet response",
-        "schema": {
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/Pet"
+        "representations": {
+          "application/json" : {
+            "schema": {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/Pet"
+              }
+            }
           }
         }
       },
       "default": {
         "description": "error payload",
-        "schema": {
-          "$ref": "#/definitions/ErrorModel"
+        "representations": {
+          "text/html" : {
+            "schema": {
+                      "$ref": "#/definitions/ErrorModel"
+               }
+            }
         }
       }
     }
@@ -410,20 +413,21 @@ get:
   description: Returns pets based on ID
   summary: Find pets by ID
   operationId: getPetsById
-  produces:
-  - application/json
-  - text/html
   responses:
     '200':
       description: pet response
-      schema:
-        type: array
-        items:
-          $ref: '#/definitions/Pet'
+      representations:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Pet'
     default:
       description: error payload
-      schema:
-        $ref: '#/definitions/ErrorModel'
+      representations:
+        text/html:
+          schema:
+            $ref: '#/definitions/ErrorModel'
 parameters:
 - name: id
   in: path
@@ -448,8 +452,6 @@ Field Name | Type | Description
 <a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
 <a name="operationExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <a name="operationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.
-<a name="operationConsumes"></a>consumes | [`string`] | A list of media types the operation can consume. This overrides the [`consumes`](#oasConsumes) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Media Types](#mediaTypes).
-<a name="operationProduces"></a>produces | [`string`] | A list of media types the operation can produce. This overrides the [`produces`](#oasProduces) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Media Types](#mediaTypes).
 <a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters).
 <a name="operationRequestBody"></a>requestBody | [[Request Body Object](#requestBodyObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The request body applicable for this operation. 
 <a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
@@ -476,13 +478,6 @@ Field Pattern | Type | Description
   "summary": "Updates a pet in the store with form data",
   "description": "",
   "operationId": "updatePetWithForm",
-  "consumes": [
-    "application/x-www-form-urlencoded"
-  ],
-  "produces": [
-    "application/json",
-    "application/xml"
-  ],
   "parameters": [
     {
       "name": "petId",
@@ -490,28 +485,39 @@ Field Pattern | Type | Description
       "description": "ID of pet that needs to be updated",
       "required": true,
       "type": "string"
-    },
-    {
-      "name": "name",
-      "in": "formData",
-      "description": "Updated name of the pet",
-      "required": false,
-      "type": "string"
-    },
-    {
-      "name": "status",
-      "in": "formData",
-      "description": "Updated status of the pet",
-      "required": false,
-      "type": "string"
     }
   ],
+  "requestBody" : {
+    "representations" : {
+      "application/x-www-form-urlencoded":{
+        "schema" : {
+           "properties": {
+              "name" 
+                "description" : "Updated name of the pet",
+                "type": "string"
+              "status":
+                "description" : "Updated status of the pet",
+                "type": "string"
+           },
+        "required" : ["status"] 
+        }
+      }
+    }
+  },
   "responses": {
     "200": {
-      "description": "Pet updated."
+      "description": "Pet updated.",
+      "representations" : {
+        "application/json" : {},
+        "application/xml" : {}
+      }
     },
     "405": {
-      "description": "Invalid input"
+      "description": "Invalid input",
+      "representations" : {
+        "application/json" : {},
+        "application/xml" : {}
+      }
     }
   },
   "security": [
@@ -531,32 +537,36 @@ tags:
 summary: Updates a pet in the store with form data
 description: ""
 operationId: updatePetWithForm
-consumes:
-- application/x-www-form-urlencoded
-produces:
-- application/json
-- application/xml
 parameters:
 - name: petId
   in: path
   description: ID of pet that needs to be updated
   required: true
   type: string
-- name: name
-  in: formData
-  description: Updated name of the pet
-  required: false
-  type: string
-- name: status
-  in: formData
-  description: Updated status of the pet
-  required: false
-  type: string
+responseBody:
+  representations:
+    application/x-www-form-urlencoded:
+      schema:
+       properties:
+          name: 
+            description: Updated name of the pet
+            type: string
+          status:
+            description: Updated status of the pet
+            type: string
+        required: 
+          - status
 responses:
   '200':
     description: Pet updated.
+    representations: 
+      application/json: {}
+      application/xml: {}
   '405':
     description: Invalid input
+    representations: 
+      application/json: {}
+      application/xml: {}
 security:
 - petstore_auth:
   - write:pets
@@ -601,14 +611,10 @@ Describes a single operation parameter.
 
 A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn).
 
-There are five possible parameter types.
+There are four possible parameter types.
 * Path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
 * Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
 * Header - Custom headers that are expected as part of the request.
-* Form - Used to describe the payload of an HTTP request when either `application/x-www-form-urlencoded`, `multipart/form-data` or both are used as the content type of the request (in the OpenAPI Specification's definition, the [`consumes`](#operationConsumes) property of an operation). This is the only parameter type that can be used to send files, thus supporting the `file` type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
-  * `application/x-www-form-urlencoded` - Similar to the format of Query parameters but as a payload. For example, `foo=1&bar=swagger` - both `foo` and `bar` are form parameters. This is normally used for simple parameters that are being transferred.
-  * `multipart/form-data` - each parameter takes a section in the payload with an internal header. For example, for the header `Content-Disposition: form-data; name="submit-name"` the name of the parameter is `submit-name`. This type of form parameters is more commonly used for file transfers.
-
 * Cookie - Used to pass a specific cookie value to the API.
 
 
@@ -618,7 +624,7 @@ For complex parameter schemas, a serialization strategy is required. For all typ
 Field Name | Type | Description
 ---|:---:|---
 <a name="parameterName"></a>name | `string` | **Required.** The name of the parameter. Parameter names are *case sensitive*. <ul><li>If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to the associated path segment from the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.<li>For all other cases, the `name` corresponds to the parameter name used based on the [`in`](#parameterIn) property.</ul>
-<a name="parameterIn"></a>in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path", "formData" or "cookie".
+<a name="parameterIn"></a>in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path" or "cookie".
 <a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use.  [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
 <a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. 
 <a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.
@@ -748,6 +754,7 @@ The `Content-Type` of the request body must be specified by the `consumes` attri
 Field Name | Type | Description
 ---|:---:|---
 <a name="requestBodyDescription"></a>description | `string` | A brief description of the request body. This could contain examples of use.  [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
+<a name="requestBodyRepresentations"></a>representations | [Representations Object](#representationsObject) | The representations of the request body.
 <a name="requestBodySchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
 <a name="requestBodyExamples"></a>examples | [Examples Object](#examplesObject) | Examples of the request body, referenced by media type.
 <a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `true`.
@@ -765,44 +772,57 @@ A request body with a referenced model definition.
 ```js
 {
   "description": "user to add to the system",
-  "schema": {
-    "$ref": "#/definitions/User"
-  },
-  "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'
+  "representations" : {
+    "application/json" : {
+      "schema": {
+          "$ref": "#/definitions/User"
+        },
+      "examples": [
+        { "$ref": 'http://foo.bar#/examples/address-example.json'}
+      ]http://foo.bar#/examples/address-example.txt
+    },
+    "application/xml" : {
+      "examples": [
+        { "$ref": 'http://foo.bar#/examples/address-example.xml'}
+      ]
+    },
+    "text/plain" : {
+      "examples": [
+        { "$ref": 'http://foo.bar#/examples/address-example.txt'}
+      ]
+    }
+  }
 }
 ```
 
 ```yaml
 description: user to add to the system
-schema:
-  $ref: '#/definitions/User'
-examples:
-        'application/json':
-          $ref: 'http://foo.bar/examples/user-example.json'
-        'application/xml':
-          $ref: 'http://foo.bar/examples/user-example.xml'
-        'text/plain':
-          $ref: 'http://foo.bar/examples/user-example.txt'
-        default:
-          $ref: 'http://foo.bar/examples/user-example.whatever'
+representations: 
+  'application/json':
+    schema:
+      $ref: '#/definitions/User'
+    examples:
+      - 'http://foo.bar/examples/user-example.json'
+  'application/xml':
+    examples:
+      - 'http://foo.bar/examples/user-example.xml'
+  'text/plain':
+    examples:
+      - 'http://foo.bar/examples/user-example.txt'
 ```
 
 A body parameter that is an array of string values:
 ```js
 {
   "description": "user to add to the system",
-  "schema": {
-    "type": "array",
-    "items": {
-      "type": "string"
+  "representations": {
+    "application/json" : {
+      "schema": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
     }
   }
 }
@@ -811,12 +831,89 @@ A body parameter that is an array of string values:
 ```yaml
 description: user to add to the system
 required: true
-schema:
-  type: array
-  items:
-    type: string
+representations:
+  application/json:
+    schema:
+      type: array
+      items:
+        type: string
+```
+
+
+#### <a name="representationsObject"></a>Representations Object
+
+Describes a set of supported representations.  A representations object can be used in [requestBody](#requestBody), [response objects](#responseObject) and [parameter objects](#parameterObject) to describe complex parameters.
+
+Each key in the representations object is the media-type of the [Representation Object](#representationObject).
+
+##### Representations Examples
+
+```js
+{
+  "application/json": {
+    "schema": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "examples": []
+  },
+  "application/xml" : {}
+}
+```
+
+```yaml
+application/json: 
+  schema:
+    type: array
+    items:
+      type: string
+application/xml: {}
+```
+
+#### <a name="representationObject"></a>Representation Object
+The representation object provides schema and examples for a the media type identified by its key.  Representation objects can be used in a [representations object](#representationsObject).   
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+<a name="representationSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
+<a name="representationExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the representation.
+
+##### Patterned Fields
+Field Pattern | Type | Description
+---|:---:|---
+<a name="parameterExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Vendor Extensions](#vendorExtensions) for further details.
+
+##### Representation Examples
+
+A representation description.
+```js
+{
+  "application/json": {
+    "schema": {
+      "type": "object",
+      "properties": {
+        "type": "string"
+      }
+    },
+    "examples": []
+  },
+  "application/xml" : {}
+}
 ```
 
+```yaml
+application/json: 
+  schema:
+    type: array
+    items:
+      type: string
+application/xml: {}
+```
+
+
 #### <a name="itemsObject"></a>Items Object
 
 A limited subset of JSON-Schema's items object. It is used by parameter definitions.

From 33ddbca76295db15146124d174035e1cf2e95ae5 Mon Sep 17 00:00:00 2001
From: Darrel <darrel@tavis.ca>
Date: Tue, 16 Aug 2016 00:43:42 -0400
Subject: [PATCH 2/6] More updates of representations

---
 versions/3.0.md | 220 +++++++++++++++++++++++++++++-------------------
 1 file changed, 133 insertions(+), 87 deletions(-)

diff --git a/versions/3.0.md b/versions/3.0.md
index 15b47c2755..3aeca416f6 100644
--- a/versions/3.0.md
+++ b/versions/3.0.md
@@ -114,9 +114,8 @@ Field Name | Type | Description
 <a name="oasVersion"></a>openapi | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version.  The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document.
 <a name="oasInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed.
 <a name="oasHosts"></a>hosts | [Hosts Object](#hostsObject) | An array of Host objects which provide `scheme`, `host`, `port`, and `basePath` in an associative manner.
-<a name="oasResponses"></a>responses | [Responses](#responsesObject)
 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API.
-<a name="oasSchemas"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
+<a name="oasComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
 <a name="oasSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition.
 <a name="oasTags"></a>tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared may be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
 <a name="oasExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
@@ -268,7 +267,7 @@ Holds a set of schemas for different aspects of the OAS.  The intention is to pu
 Field Pattern | Type | Description
 ---|:---:|---
 <a name="definitionsObject"></a> | [Definitions Object](#definitionsObject) | A hash containing payload definitions for the specification.
-<a name="responsesDefinitionsObject"></a> | Responses Definitions Object | Reusable responses objects.
+<a name="responsesDefinitionsObject"></a> | [Responses Definitions Object](#responsesDefinitionsObject) | Reusable responses objects.
 <a name="parametersDefinitionsObject"></a> | [Parameters Definitions Object](#parametersDefinitionsObject) | An object to hold parameters to be reused across operations. Parameter definitions can be referenced to the ones defined here.
 <a name="responseHeadersDefinitionsObject"></a> | [Response Headers Definitions Object](#responseHeadersDefinitionsObject) | Response headers to reuse across the specification.
 <a name="securityDefinitionsObject"></a> | [Security Definitions Object](#securityDefinitionsObject) | Security definitions to reuse across the specification.
@@ -417,7 +416,7 @@ get:
     '200':
       description: pet response
       representations:
-        application/json:
+        'application/json':
           schema:
             type: array
             items:
@@ -425,7 +424,7 @@ get:
     default:
       description: error payload
       representations:
-        text/html:
+        'text/html':
           schema:
             $ref: '#/definitions/ErrorModel'
 parameters:
@@ -545,7 +544,7 @@ parameters:
   type: string
 responseBody:
   representations:
-    application/x-www-form-urlencoded:
+    'application/x-www-form-urlencoded':
       schema:
        properties:
           name: 
@@ -560,13 +559,13 @@ responses:
   '200':
     description: Pet updated.
     representations: 
-      application/json: {}
-      application/xml: {}
+      'application/json': {}
+      'application/xml': {}
   '405':
     description: Invalid input
     representations: 
-      application/json: {}
-      application/xml: {}
+      'application/json': {}
+      'application/xml': {}
 security:
 - petstore_auth:
   - write:pets
@@ -756,7 +755,6 @@ Field Name | Type | Description
 <a name="requestBodyDescription"></a>description | `string` | A brief description of the request body. This could contain examples of use.  [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
 <a name="requestBodyRepresentations"></a>representations | [Representations Object](#representationsObject) | The representations of the request body.
 <a name="requestBodySchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
-<a name="requestBodyExamples"></a>examples | [Examples Object](#examplesObject) | Examples of the request body, referenced by media type.
 <a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `true`.
 
 
@@ -779,7 +777,7 @@ A request body with a referenced model definition.
         },
       "examples": [
         { "$ref": 'http://foo.bar#/examples/address-example.json'}
-      ]http://foo.bar#/examples/address-example.txt
+      ]
     },
     "application/xml" : {
       "examples": [
@@ -832,7 +830,7 @@ A body parameter that is an array of string values:
 description: user to add to the system
 required: true
 representations:
-  application/json:
+  'application/json':
     schema:
       type: array
       items:
@@ -849,7 +847,7 @@ Each key in the representations object is the media-type of the [Representation
 ##### Representations Examples
 
 ```js
-{
+"representations" : {
   "application/json": {
     "schema": {
       "type": "array",
@@ -864,12 +862,13 @@ Each key in the representations object is the media-type of the [Representation
 ```
 
 ```yaml
-application/json: 
-  schema:
-    type: array
-    items:
-      type: string
-application/xml: {}
+representations:
+  'application/json': 
+    schema:
+      type: array
+      items:
+        type: string
+  'application/xml': {}
 ```
 
 #### <a name="representationObject"></a>Representation Object
@@ -947,7 +946,7 @@ Field Pattern | Type | Description
 
 ##### Items Object Examples
 
-Items must be of type  string and have the minimum length of  2 characters:
+Items must be of type string and have the minimum length of  2 characters:
 
 ```js
 {
@@ -1010,14 +1009,22 @@ A 200 response for successful operation and a default response for others (imply
 {
   "200": {
     "description": "a pet to be returned",
-    "schema": {
-      "$ref": "#/definitions/Pet"
+    "representations" : {
+        "application/json" : {
+              "schema": {
+            "$ref": "#/definitions/Pet"
+          }
+        }
     }
   },
   "default": {
     "description": "Unexpected error",
-    "schema": {
-      "$ref": "#/definitions/ErrorModel"
+    "representations" : {
+        "application/json" : {
+          "schema": {
+            "$ref": "#/definitions/ErrorModel"
+          }
+        }
     }
   }
 }
@@ -1026,12 +1033,16 @@ A 200 response for successful operation and a default response for others (imply
 ```yaml
 '200':
   description: a pet to be returned
-  schema:
-    $ref: '#/definitions/Pet'
+  representations: 
+    'application/json':
+      schema:
+        $ref: '#/definitions/Pet'
 default:
   description: Unexpected error
-  schema:
-    $ref: '#/definitions/ErrorModel'
+  representations:
+    'application/json':
+      schema:
+        $ref: '#/definitions/ErrorModel'
 ```
 
 #### <a name="responseObject"></a>Response Object
@@ -1041,9 +1052,8 @@ Describes a single response from an API Operation, including design-time, static
 Field Name | Type | Description
 ---|:---:|---
 <a name="responseDescription"></a>description | `string` | **Required.** A short description of the response. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
-<a name="responseSchema"></a>schema | [Schema Object](#schemaObject) | A definition of the response structure. It can be a primitive, an array or an object. If this field does not exist, it means no content is returned as part of the response. As an extension to the [Schema Object](#schemaObject), its root `type` value may also be `"file"`. This SHOULD be accompanied by a relevant `produces` media type.
 <a name="responseHeaders"></a>headers | [Headers Object](#headersObject) | A list of headers that are sent with the response.
-<a name="responseExamples"></a>examples | [Example Object](#exampleObject) | An example of the response message.
+<a name="responseRepresentations"></a>representations | [Representations Object](#representationsObject) | An object containing descriptions of potential response payloads.
 <a name="responseLinks"></a>links | [Links Object](#linksObject) | An object representing operations related to the response payload.
 
 
@@ -1060,10 +1070,14 @@ Response of an array of a complex type:
 ```js
 {
   "description": "A complex object array response",
-  "schema": {
-    "type": "array",
-    "items": {
-      "$ref": "#/definitions/VeryComplexType"
+  "representations" : {
+    "application/json" : {
+      "schema": {
+        "type": "array",
+        "items": {
+          "$ref": "#/definitions/VeryComplexType"
+        }
+      }
     }
   }
 }
@@ -1071,10 +1085,12 @@ Response of an array of a complex type:
 
 ```yaml
 description: A complex object array response
-schema:
-  type: array
-  items:
-    $ref: '#/definitions/VeryComplexType'
+representations: 
+  'application/json':
+    schema: 
+      type: array
+      items:
+        $ref: '#/definitions/VeryComplexType'
 ```
 
 Response with a string type:
@@ -1082,9 +1098,14 @@ Response with a string type:
 ```js
 {
   "description": "A simple string response",
-  "schema": {
-    "type": "string"
+  "representations" : {
+    "application/json" : {
+      "schema": {
+        "type": "string"
+      }
+    }
   }
+
 }
 ```
 
@@ -1099,8 +1120,12 @@ Response with headers:
 ```js
 {
   "description": "A simple string response",
-  "schema": {
-    "type": "string"
+  "representations" : {
+    "application/json" : {
+      "schema": {
+        "type": "string"
+      }
+    }
   },
   "headers": {
     "X-Rate-Limit-Limit": {
@@ -1121,8 +1146,10 @@ Response with headers:
 
 ```yaml
 description: A simple string response
-schema:
-  type: string
+representations:
+  'application/json':
+    schema:
+      type: string
 headers:
   X-Rate-Limit-Limit:
     description: The number of allowed requests in the current period
@@ -1188,7 +1215,7 @@ X-Rate-Limit-Reset:
   type: integer
 ```
 
-#### <a name="exampleObject"></a>Example Object
+#### <a name="examplesObject"></a>Examples Object
 
 Allows sharing examples for operation requests and responses.
 
@@ -1197,24 +1224,24 @@ Field Pattern | Type | Description
 ---|:---:|---
 <a name="exampleMediaType"></a>{[media type](#mediaTypes)} | Any | The name of the property MUST be one of the Operation `produces` values (either implicit or inherited). The value SHOULD be an example of what such a response would look like. 
 
-##### Example Object Example
+##### Examples Array Example
 
-Example request or response for application/json media type of a Pet data type:
+Example representation for application/json media type of a Pet data type:
 
 ```js
-{
-  "application/json": {
+[
+  {
     "name": "Puma",
     "type": "Dog",
     "color": "Black",
     "gender": "Female",
     "breed": "Mixed"
   }
-}
+]
 ```
 
 ```yaml
-application/json:
+-
   name: Puma
   type: Dog
   color: Black
@@ -1325,12 +1352,14 @@ paths:
     responses:
       200:
         description: the user being returned
-        schema:
-          type: object
-          properties:
-            uuid: the unique user id
-              type: string
-              format: uuid
+        representations:
+          'application/json':
+            schema:
+              type: object
+              properties:
+                uuid: the unique user id
+                  type: string
+                  format: uuid
 ```
 
 Can be used in a link like this:
@@ -1394,9 +1423,11 @@ paths:
         required: true
       responses: 
         200: 
-          description: The User 
-          schema: 
-            $ref: '#/components/definitions/user'
+          description: The User
+          representations:
+            'application/json': 
+              schema: 
+                $ref: '#/components/definitions/user'
           links:
             userRepositories:
               $ref: '#/components/links/UserRepositories'
@@ -1411,10 +1442,12 @@ paths:
       responses:
         200:
           description: repositories owned by the supplied user
-          schema:
-            type: array
-            items:
-              $ref: '#/components/definitions/repository'
+          representations: 
+            'application/json':
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/definitions/repository'
           links:
             userRepository:
               $ref: '#/components/links/UserRepository'
@@ -1432,9 +1465,11 @@ paths:
           required: true
       responses: 
         200:
-          description: The repository 
-          schema: 
-            $ref: '#/components/definitions/repository'
+          description: The repository
+            representations:
+              'application/json': 
+                schema: 
+                  $ref: '#/components/definitions/repository'
           links:
             repositoryPullRequests:
               $ref: '#/components/links/RepositoryPullRequests'
@@ -1460,10 +1495,12 @@ paths:
       responses: 
         200: 
           description: an array of pull request objects
-          schema: 
-            type: array
-            items: 
-              $ref: '#/components/definitions/pullrequest'
+          representations:
+            'application/json': 
+              schema: 
+                type: array
+                items: 
+                  $ref: '#/components/definitions/pullrequest'
   /2.0/repositories/{username}/{slug}/pullrequests/{pid}: 
     get: 
       operationId: getPullRequestsById
@@ -1483,8 +1520,10 @@ paths:
       responses: 
         200: 
           description: a pull request object
-          schema: 
-            $ref: '#/components/definitions/pullrequest'
+          representations:
+            'application/json': 
+            schema: 
+              $ref: '#/components/definitions/pullrequest'
           links:
             $ref: '#/components/links/PullRequestMerge'
   /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge: 
@@ -1707,17 +1746,22 @@ definitions:
 
 # in a request body, note the plural `examples` as the content-type is set by `consumes`:
 	requestBody:
-      schema:
-        $ref: '#/definitions/Address'
-      examples:
-        'application/json':
-          $ref: 'http://foo.bar#/examples/address-example.json'
+      representations:
+       'application/json':
+          schema:
+            $ref: '#/definitions/Address'
+          examples: 
+                - 
+                  $ref: 'http://foo.bar#/examples/address-example.json' 
         'application/xml':
-          $ref: 'http://foo.bar#/examples/address-example.xml'
+          examples: 
+            -   
+              $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'
+          examples: 
+            -
+              $ref: 'http://foo.bar#/examples/address-example.txt' 
+        
 
 # in a parameter
 
@@ -1732,11 +1776,13 @@ definitions:
   responses:
     200:
       description: your car appointment has been booked
-      schema:
-        $ref: '#/definitions/SuccessResponse'
-      examples:
+      representations: 
         'application/json':
-          $ref: http://foo.bar#/examples/address-example.json
+          schema:
+            $ref: '#/definitions/SuccessResponse'
+          examples:
+            -
+              $ref: http://foo.bar#/examples/address-example.json
 ```
 
 #### <a name="referenceObject"></a>Reference Object

From d5e2feba2a56209c9ab28a3a10041d6c0da9358c Mon Sep 17 00:00:00 2001
From: Darrel <darrel@tavis.ca>
Date: Wed, 17 Aug 2016 21:52:38 -0400
Subject: [PATCH 3/6] Expanded representations examples

---
 versions/3.0.md | 36 ++++++++++++++++++++++++++++++++----
 1 file changed, 32 insertions(+), 4 deletions(-)

diff --git a/versions/3.0.md b/versions/3.0.md
index cf4b249145..64bdd5b25e 100644
--- a/versions/3.0.md
+++ b/versions/3.0.md
@@ -840,7 +840,7 @@ representations:
 
 #### <a name="representationsObject"></a>Representations Object
 
-Describes a set of supported representations.  A representations object can be used in [requestBody](#requestBody), [response objects](#responseObject) and [parameter objects](#parameterObject) to describe complex parameters.
+Describes a set of supported representations.  A representations object can be used in [requestBody](#requestBody) and [response objects](#responseObject).
 
 Each key in the representations object is the media-type of the [Representation Object](#representationObject).
 
@@ -849,15 +849,29 @@ Each key in the representations object is the media-type of the [Representation
 ```js
 "representations" : {
   "application/json": {
+   'application/json':
+
     "schema": {
       "type": "array",
       "items": {
         "type": "string"
       }
     },
-    "examples": []
+    "examples": [
+      ["Bob","Diane","Mary","Bill"],
+      []
+     ]
   },
-  "application/xml" : {}
+  "application/xml" : {
+    "examples" : [
+      "<Users><User name='Bob'/><User name='Diane'/><User name='Mary'/><User name='Bill'/></Users>",
+      "<Users/>"
+    ]
+  },
+  "text/plain" : {
+    "Bob,Diane,Mary,Bill",
+    ""
+  }
 }
 ```
 
@@ -868,7 +882,21 @@ representations:
       type: array
       items:
         type: string
-  'application/xml': {}
+    examples:
+      - 
+        - Bob
+        - Diane
+        - Mary
+        - Bill
+      - {}
+
+  'application/xml': 
+    examples:
+      - "<Users><User name='Bob'/><User name='Diane'/><User name='Mary'/><User name='Bill'/></Users>"
+      - "<Users/>"
+  'text/plain':
+    examples:
+      - "Bob,Diane,Mary,Bill"
 ```
 
 #### <a name="representationObject"></a>Representation Object

From 566ce996e1e3f29fff0b8d5aaf06a63ff68814bf Mon Sep 17 00:00:00 2001
From: Darrel <darrel@tavis.ca>
Date: Thu, 18 Aug 2016 10:35:35 -0400
Subject: [PATCH 4/6] Updating representation example

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

diff --git a/versions/3.0.md b/versions/3.0.md
index 64bdd5b25e..4e46e19ac5 100644
--- a/versions/3.0.md
+++ b/versions/3.0.md
@@ -337,8 +337,8 @@ A Path Item may be empty, due to [ACL constraints](#securityFiltering). The path
 Field Name | Type | Description
 ---|:---:|---
 <a name="pathItemRef"></a>$ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). If there are conflicts between the referenced definition and this Path Item's definition, the behavior is *undefined*.
-<a name="pathItemSummary"></a>summary | An optional, string summary, intended to apply to all operations in this path.
-<a name="pathItemDescription"></a>description | An optional, string description, intended to apply to all operations in this path.
+<a name="pathItemSummary"></a>summary| `string` | An optional, string summary, intended to apply to all operations in this path.
+<a name="pathItemDescription"></a>description | `string` | An optional, string description, intended to apply to all operations in this path.
 <a name="pathItemGet"></a>get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
 <a name="pathItemPut"></a>put | [Operation Object](#operationObject) | A definition of a PUT operation on this path.
 <a name="pathItemPost"></a>post | [Operation Object](#operationObject) | A definition of a POST operation on this path.
@@ -754,7 +754,6 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="requestBodyDescription"></a>description | `string` | A brief description of the request body. This could contain examples of use.  [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
 <a name="requestBodyRepresentations"></a>representations | [Representations Object](#representationsObject) | The representations of the request body.
-<a name="requestBodySchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
 <a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `true`.
 
 
@@ -849,8 +848,6 @@ Each key in the representations object is the media-type of the [Representation
 ```js
 "representations" : {
   "application/json": {
-   'application/json':
-
     "schema": {
       "type": "array",
       "items": {
@@ -920,24 +917,30 @@ A representation description.
 {
   "application/json": {
     "schema": {
-      "type": "object",
-      "properties": {
-        "type": "string"
-      }
+         "$ref": "#/definitions/Pet"
     },
-    "examples": []
-  },
-  "application/xml" : {}
+    "examples": [{
+                  "name" : "Fluffy",
+                  "petType" : "Cat"
+                 },
+                 { 
+                   "name" : "Rover",
+                   "petType" : "Frog"
+                 }]
+  }
 }
 ```
 
 ```yaml
 application/json: 
   schema:
-    type: array
-    items:
-      type: string
-application/xml: {}
+    $ref: "#/definitions/Pet"
+  examples:
+    - name: Fluffy
+      petType: Cat
+    - name: Rover
+      petType: Frog
+
 ```
 
 

From 9cb8c2c490714752259f73bef822e6bbc6f0c77d Mon Sep 17 00:00:00 2001
From: Darrel <darrel@tavis.ca>
Date: Fri, 9 Sep 2016 22:41:58 -0400
Subject: [PATCH 5/6] Fixed issues mentioned in comments

---
 versions/3.0.md | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/versions/3.0.md b/versions/3.0.md
index d838a9f8de..c52779cc90 100644
--- a/versions/3.0.md
+++ b/versions/3.0.md
@@ -297,12 +297,12 @@ Field Pattern | Type | Description
           "description": "A list of pets.",
           "representations" : {
             "application/json" : {
-                "schema": {
-                            "type": "array",
-                            "items": {
-                              "$ref": "#/definitions/pet"
-                            }
-                          }
+              "schema": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/definitions/pet"
+                }
+              }
             }
           }
         }
@@ -384,9 +384,9 @@ Field Pattern | Type | Description
         "representations": {
           "text/html" : {
             "schema": {
-                      "$ref": "#/definitions/ErrorModel"
-               }
+              "$ref": "#/definitions/ErrorModel"
             }
+          }
         }
       }
     }
@@ -490,6 +490,7 @@ Field Pattern | Type | Description
     "representations" : {
       "application/x-www-form-urlencoded":{
         "schema" : {
+          "type" : "object",
            "properties": {
               "name" 
                 "description" : "Updated name of the pet",

From 5396c3794b20f293d0bf532b45e5035714d7a823 Mon Sep 17 00:00:00 2001
From: Darrel <darrel@tavis.ca>
Date: Fri, 9 Sep 2016 23:06:24 -0400
Subject: [PATCH 6/6] Renamed representations to content

---
 versions/3.0.md | 101 ++++++++++++++++++++++--------------------------
 1 file changed, 47 insertions(+), 54 deletions(-)

diff --git a/versions/3.0.md b/versions/3.0.md
index 57470b6806..854430014c 100644
--- a/versions/3.0.md
+++ b/versions/3.0.md
@@ -295,7 +295,7 @@ Field Pattern | Type | Description
       "responses": {
         "200": {          
           "description": "A list of pets.",
-          "representations" : {
+          "content" : {
             "application/json" : {
               "schema": {
                 "type": "array",
@@ -319,7 +319,7 @@ Field Pattern | Type | Description
     responses:
       '200':
         description: A list of pets.
-        representations:
+        content:
           'application/json':
             schema:
               type: array
@@ -368,7 +368,7 @@ Field Pattern | Type | Description
     "responses": {
       "200": {
         "description": "pet response",
-        "representations": {
+        "content": {
           "application/json" : {
             "schema": {
               "type": "array",
@@ -381,7 +381,7 @@ Field Pattern | Type | Description
       },
       "default": {
         "description": "error payload",
-        "representations": {
+        "content": {
           "text/html" : {
             "schema": {
               "$ref": "#/definitions/ErrorModel"
@@ -415,7 +415,7 @@ get:
   responses:
     '200':
       description: pet response
-      representations:
+      content:
         'application/json':
           schema:
             type: array
@@ -423,7 +423,7 @@ get:
               $ref: '#/definitions/Pet'
     default:
       description: error payload
-      representations:
+      content:
         'text/html':
           schema:
             $ref: '#/definitions/ErrorModel'
@@ -487,7 +487,7 @@ Field Pattern | Type | Description
     }
   ],
   "requestBody" : {
-    "representations" : {
+    "content" : {
       "application/x-www-form-urlencoded":{
         "schema" : {
           "type" : "object",
@@ -507,14 +507,14 @@ Field Pattern | Type | Description
   "responses": {
     "200": {
       "description": "Pet updated.",
-      "representations" : {
+      "content" : {
         "application/json" : {},
         "application/xml" : {}
       }
     },
     "405": {
       "description": "Invalid input",
-      "representations" : {
+      "content" : {
         "application/json" : {},
         "application/xml" : {}
       }
@@ -544,7 +544,7 @@ parameters:
   required: true
   type: string
 responseBody:
-  representations:
+  content:
     'application/x-www-form-urlencoded':
       schema:
        properties:
@@ -559,12 +559,12 @@ responseBody:
 responses:
   '200':
     description: Pet updated.
-    representations: 
+    content: 
       'application/json': {}
       'application/xml': {}
   '405':
     description: Invalid input
-    representations: 
+    content: 
       'application/json': {}
       'application/xml': {}
 security:
@@ -624,13 +624,8 @@ For complex parameter schemas, a serialization strategy is required. For all typ
 Field Name | Type | Description
 ---|:---:|---
 <a name="parameterName"></a>name | `string` | **Required.** The name of the parameter. Parameter names are *case sensitive*. <ul><li>If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to the associated path segment from the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.<li>For all other cases, the `name` corresponds to the parameter name used based on the [`in`](#parameterIn) property.</ul>
-<<<<<<< HEAD
-<a name="parameterIn"></a>in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path" or "cookie".
-<a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use.  [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
-=======
 <a name="parameterIn"></a>in | `string` | **Required.** The location of the parameter. Possible values are "query", "header", "path", "formData" or "cookie".
 <a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use.  [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
->>>>>>> OpenAPI.next
 <a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. 
 <a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.
 <a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.
@@ -753,13 +748,11 @@ schema:
 
 Describes a single request body.
 
-The `Content-Type` of the request body must be specified by the `consumes` attribute, either at the [top-level](#oasConsumes) or [operation level](#operationConsumes).
-
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
 <a name="requestBodyDescription"></a>description | `string` | A brief description of the request body. This could contain examples of use.  [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
-<a name="requestBodyRepresentations"></a>representations | [Representations Object](#representationsObject) | The representations of the request body.
+<a name="requestBodyContent"></a>content | [Content Object](#contentObject) | The content of the request body.
 <a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `true`.
 
 
@@ -775,7 +768,7 @@ A request body with a referenced model definition.
 ```js
 {
   "description": "user to add to the system",
-  "representations" : {
+  "content" : {
     "application/json" : {
       "schema": {
           "$ref": "#/definitions/User"
@@ -800,7 +793,7 @@ A request body with a referenced model definition.
 
 ```yaml
 description: user to add to the system
-representations: 
+content: 
   'application/json':
     schema:
       $ref: '#/definitions/User'
@@ -818,7 +811,7 @@ A body parameter that is an array of string values:
 ```js
 {
   "description": "user to add to the system",
-  "representations": {
+  "content": {
     "application/json" : {
       "schema": {
         "type": "array",
@@ -834,7 +827,7 @@ A body parameter that is an array of string values:
 ```yaml
 description: user to add to the system
 required: true
-representations:
+content:
   'application/json':
     schema:
       type: array
@@ -843,16 +836,16 @@ representations:
 ```
 
 
-#### <a name="representationsObject"></a>Representations Object
+#### <a name="contentObject"></a>Content Object
 
-Describes a set of supported representations.  A representations object can be used in [requestBody](#requestBody) and [response objects](#responseObject).
+Describes a set of supported content types. A content object can be used in [requestBody](#requestBody) and [response objects](#responseObject).
 
-Each key in the representations object is the media-type of the [Representation Object](#representationObject).
+Each key in the content object is the media-type of the [Content Type Object](#contentTypeObject).
 
-##### Representations Examples
+##### Content Examples
 
 ```js
-"representations" : {
+"content" : {
   "application/json": {
     "schema": {
       "type": "array",
@@ -879,7 +872,7 @@ Each key in the representations object is the media-type of the [Representation
 ```
 
 ```yaml
-representations:
+content:
   'application/json': 
     schema:
       type: array
@@ -902,23 +895,23 @@ representations:
       - "Bob,Diane,Mary,Bill"
 ```
 
-#### <a name="representationObject"></a>Representation Object
-The representation object provides schema and examples for a the media type identified by its key.  Representation objects can be used in a [representations object](#representationsObject).   
+#### <a name="contentTypeObject"></a>Content Type Object
+Each content type object provides schema and examples for a the media type identified by its key.  Content Type objects can be used in a [content object](#contentObject).   
 
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-<a name="representationSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
-<a name="representationExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the representation.
+<a name="contentTypeSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
+<a name="contentTypeExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the content type.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
 <a name="parameterExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Vendor Extensions](#vendorExtensions) for further details.
 
-##### Representation Examples
+##### Content Type Examples
 
-A representation description.
+A content type description.
 ```js
 {
   "application/json": {
@@ -1046,7 +1039,7 @@ A 200 response for successful operation and a default response for others (imply
 {
   "200": {
     "description": "a pet to be returned",
-    "representations" : {
+    "content" : {
         "application/json" : {
               "schema": {
             "$ref": "#/definitions/Pet"
@@ -1056,7 +1049,7 @@ A 200 response for successful operation and a default response for others (imply
   },
   "default": {
     "description": "Unexpected error",
-    "representations" : {
+    "content" : {
         "application/json" : {
           "schema": {
             "$ref": "#/definitions/ErrorModel"
@@ -1070,13 +1063,13 @@ A 200 response for successful operation and a default response for others (imply
 ```yaml
 '200':
   description: a pet to be returned
-  representations: 
+  content: 
     'application/json':
       schema:
         $ref: '#/definitions/Pet'
 default:
   description: Unexpected error
-  representations:
+  content:
     'application/json':
       schema:
         $ref: '#/definitions/ErrorModel'
@@ -1090,7 +1083,7 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="responseDescription"></a>description | `string` | **Required.** A short description of the response. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="responseHeaders"></a>headers | [Headers Object](#headersObject) | A list of headers that are sent with the response.
-<a name="responseRepresentations"></a>representations | [Representations Object](#representationsObject) | An object containing descriptions of potential response payloads.
+<a name="responseRepresentations"></a>content | [Content Object](#contentObject) | An object containing descriptions of potential response payloads.
 <a name="responseLinks"></a>links | [Links Object](#linksObject) | An object representing operations related to the response payload.
 
 
@@ -1107,7 +1100,7 @@ Response of an array of a complex type:
 ```js
 {
   "description": "A complex object array response",
-  "representations" : {
+  "content" : {
     "application/json" : {
       "schema": {
         "type": "array",
@@ -1122,7 +1115,7 @@ Response of an array of a complex type:
 
 ```yaml
 description: A complex object array response
-representations: 
+content: 
   'application/json':
     schema: 
       type: array
@@ -1135,7 +1128,7 @@ Response with a string type:
 ```js
 {
   "description": "A simple string response",
-  "representations" : {
+  "content" : {
     "application/json" : {
       "schema": {
         "type": "string"
@@ -1157,7 +1150,7 @@ Response with headers:
 ```js
 {
   "description": "A simple string response",
-  "representations" : {
+  "content" : {
     "application/json" : {
       "schema": {
         "type": "string"
@@ -1183,7 +1176,7 @@ Response with headers:
 
 ```yaml
 description: A simple string response
-representations:
+content:
   'application/json':
     schema:
       type: string
@@ -1389,7 +1382,7 @@ paths:
     responses:
       200:
         description: the user being returned
-        representations:
+        content:
           'application/json':
             schema:
               type: object
@@ -1461,7 +1454,7 @@ paths:
       responses: 
         200: 
           description: The User
-          representations:
+          content:
             'application/json': 
               schema: 
                 $ref: '#/components/definitions/user'
@@ -1479,7 +1472,7 @@ paths:
       responses:
         200:
           description: repositories owned by the supplied user
-          representations: 
+          content: 
             'application/json':
               schema:
                 type: array
@@ -1503,7 +1496,7 @@ paths:
       responses: 
         200:
           description: The repository
-            representations:
+            content:
               'application/json': 
                 schema: 
                   $ref: '#/components/definitions/repository'
@@ -1532,7 +1525,7 @@ paths:
       responses: 
         200: 
           description: an array of pull request objects
-          representations:
+          content:
             'application/json': 
               schema: 
                 type: array
@@ -1557,7 +1550,7 @@ paths:
       responses: 
         200: 
           description: a pull request object
-          representations:
+          content:
             'application/json': 
             schema: 
               $ref: '#/components/definitions/pullrequest'
@@ -1783,7 +1776,7 @@ definitions:
 
 # in a request body, note the plural `examples` as the content-type is set by `consumes`:
 	requestBody:
-      representations:
+      content:
        'application/json':
           schema:
             $ref: '#/definitions/Address'
@@ -1813,7 +1806,7 @@ definitions:
   responses:
     200:
       description: your car appointment has been booked
-      representations: 
+      content: 
         'application/json':
           schema:
             $ref: '#/definitions/SuccessResponse'