Merge remote-tracking branch 'refs/remotes/origin/OpenAPI.next' into dm/components

# Conflicts:
#	versions/3.0.md

Author: darrelmiller

versions/3.0.md

@@ -108,7 +108,7 @@ For example, if a field has an array value, the JSON array representation will b
 }
 ```
 
-While the API is described using JSON it does not impose a JSON input/output to the API itself.
+While the API is described using JSON, it does not impose a JSON input/output to the API itself.
 
 All field names in the specification are **case sensitive**.
 
@@ -213,7 +213,7 @@ Field Name | Type | Description
 <a name="infoTermsOfService"></a>termsOfService | `string` | A URL to the Terms of Service for the API.
 <a name="infoContact"></a>contact | [Contact Object](#contactObject) | The contact information for the exposed API.
 <a name="infoLicense"></a>license | [License Object](#licenseObject) | The license information for the exposed API.
-<a name="infoVersion"></a>version | `string` | **Required** The version of the API definition (which is distinct from the OpenAPI specification version or the API implementation version).
+<a name="infoVersion"></a>version | `string` | **Required.** The version of the API definition (which is distinct from the OpenAPI specification version or the API implementation version).
 
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
@@ -741,7 +741,7 @@ Field Name | Type | Description
 <a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) 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="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="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.  The `requestBody` is only supported in HTTP methods where the [HTTP 1.1 specification](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies.  In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers.
 <a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
 <a name="operationCallbacks"></a>callbacks | [Callbacks Object](#callbacksObject) | The list of possible callbacks as they are returned from executing this operation.
@@ -1095,7 +1095,7 @@ Field Name | Type | Description
 Field Pattern | Type | Description
 ---|:---:|---
 <a name="requestBodyRepresentation"></a>`*` | [Schema Object](#schemaObject) | The schema defining the request body.
-<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.
+<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 [Specification Extensions](#specificationExtensions) for further details.
 
 
 ##### Request Body Examples
@@ -1253,7 +1253,7 @@ Field Name | Type | Description
 ##### 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.
+<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 [Specification Extensions](#specificationExtensions) for further details.
 
 ##### Content Type Examples
 
@@ -1405,28 +1405,14 @@ In scenarios where more control is needed over the Content-Type for `multipart`
 
 #### <a name="encodingObject"></a>Encoding Object
 
-An object representing multipart region encoding for `requestBody` objects
+An object representing multipart region encoding for `requestBody` objects.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="encodingObjectProperty"></a>The property to apply encoding to | [Encoding Property](#encodingProperty) <span>&#124;</span> [Encoding](#encoding) | The field name to apply special encoding attributes to.  This field MUST exist in the schema as a property.
+<a name="encodingProperty"></a>{property} | [Encoding Property Object](#encodingPropertyObject) | The property name to which the special encoding are applied.  This field MUST exist in the schema as a property.
 
-#### <a name="encoding"></a>Encoding
-
-A single encoding definition applied to a single schema property
-
-##### Fixed Fields
-Field Name | Type | Description
----|:---:|---
-<a name="encodingContentType"></a>contentType | `string` | The content-type to use for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` - `application/octet-stream`; for other primitive types - `plain/text`; for `object` - `application/json`; for `array` - the default is defined based on the inner type.
-<a name="encodingHeaders"></a>Headers | `object` | A string map allowing additional information to be provided as headers, for example `Content-Disposition`.  Note `Content-Type` is described separately and will be ignored from this section.
-<a name="encodingStyle"></a>style | `string` | The content-type to use for encoding a specific property.  See (#parameterContent) for details on the [`style`](#parameterStyle) property. The behavior follows the same values allowed for `query` parameters, including default values.
-<a name="encodingExplode"></a>explode | `boolean` | When this is true, property 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 properties this property has no effect. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
-
-This object can be extended with [Specification Extensions](#specificationExtensions). 
-
-##### Encoding Object Examples
+##### Encoding Object Example
 
 ```yaml
 requestBody:
@@ -1461,6 +1447,20 @@ requestBody:
           contentType: image/png, image/jpeg
 ```
 
+#### <a name="encodingPropertyObject"></a>Encoding Property Object
+
+A single encoding definition applied to a single schema property.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+<a name="encodingContentType"></a>contentType | `string` | The content-type to use for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` - `application/octet-stream`; for other primitive types - `plain/text`; for `object` - `application/json`; for `array` - the default is defined based on the inner type.
+<a name="encodingHeaders"></a>Headers | `object` | A string map allowing additional information to be provided as headers, for example `Content-Disposition`.  Note `Content-Type` is described separately and will be ignored from this section.
+<a name="encodingStyle"></a>style | `string` | The content-type to use for encoding a specific property.  See (#parameterContent) for details on the [`style`](#parameterStyle) property. The behavior follows the same values allowed for `query` parameters, including default values.
+<a name="encodingExplode"></a>explode | `boolean` | When this is true, property 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 properties this property has no effect. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
+
+This object can be extended with [Specification Extensions](#specificationExtensions). 
+
 #### <a name="responsesObject"></a>Responses Object
 
 A container for the expected responses of an operation.
@@ -1920,7 +1920,7 @@ color: ["red", "green", "blue"]
 The variables generated can be used in locations prescribed by the definition.
 
 
-### <a name="variableSubstitution"></a>Variable substitution
+### <a name="variableSubstitution"></a>Variable Substitution
 In all cases, _variables_ from request and responses may be substituted for link generation.
 The table below provides examples of variable expressions and examples of their use in a value:
 
@@ -1956,7 +1956,7 @@ The variable expression is defined by the following [ABNF](https://tools.ietf.or
 The `name` identifier is case-sensitive, whereas `token` is not. 
 
 
-### Request parameter example
+### Request Parameter Example
 Computing a link from a request operation like such:
 
 ```yaml
@@ -1996,7 +1996,7 @@ For a `id` value of `10101110`, the generated link would be:
 href: '/users/10101110/department'
 ```
 
-### Response payload example
+### Response Payload Example
 
 ```yaml
 Addresses:
@@ -3248,7 +3248,7 @@ Field Name | Type | Validity | Description
 <a name="securitySchemeType"></a>type | `string` | Any | **Required.** The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`.
 <a name="securitySchemeDescription"></a>description | `string` | Any | A short description for security scheme.
 <a name="securitySchemeName"></a>name | `string` | `apiKey` | **Required.** The name of the header or query parameter to be used.
-<a name="securitySchemeIn"></a>in | `string` | `apiKey` | **Required** The ___location of the API key. Valid values are `"query"` or `"header"`.
+<a name="securitySchemeIn"></a>in | `string` | `apiKey` | **Required.** The ___location of the API key. Valid values are `"query"` or `"header"`.
 <a name="securitySchemeScheme"></a>scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC 7235](https://tools.ietf.org/html/rfc7235#section-4.2).
 <a name="securitySchemeBearerFormat"></a>bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted.  Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
 <a name="securitySchemeFlow"></a>flow | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **Required.** An object containing configuration information for the flow types supported. 
@@ -3501,7 +3501,7 @@ Two examples for this:
 
 Version | Date | Notes
 ---   | --- | ---
-3.0.0-rc0 | 2017-02-28 | Implementor's draft of the 3.0 specification
+3.0.0-rc0 | 2017-02-28 | Implementer's Draft of the 3.0 specification
 2.0   | 2015-12-31 | Donation of Swagger 2.0 to the Open API Initiative
 2.0   | 2014-09-08 | Release of Swagger 2.0
 1.2   | 2014-03-14 | Initial release of the formal document.