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

darrelmiller · darrelmiller · commit d4938cbcb2aa · 2017-02-28T00:20:12.000-05:00
# Conflicts:
#	versions/3.0.md
diff --git a/versions/3.0.md b/versions/3.0.md
@@ -112,7 +112,7 @@ While the API is described using JSON it does not impose a JSON input/output to
 All field names in the specification are **case sensitive**.
 
 The schema exposes two types of fields.
-Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.
+Fixed fields, which have a declared name, and Patterned fields, which declare a regular expression pattern for the field name.
 Patterned fields can have multiple occurrences as long as each has a unique name. 
 
 In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](http://www.yaml.org/spec/1.2/spec.html) is recommended along with some additional constraints:
@@ -210,7 +210,8 @@ 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** Provides the version of the application API (not to be confused with the specification version).  While not required, is it suggested that the `info.version` value correspond to the version of the API definition.  In practice, the version of the API _implementation_ MAY evolve at an entirely different rate.
+<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). 
 
@@ -1246,6 +1247,7 @@ Field Name | Type | Description
 <a name="contentTypeSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
 <a name="contentTypeExamples"></a>examples | [[Example Object](#exampleObject) <span>&#124;</span> [Reference Object](#referenceObject)] | Examples of the content type.  Each example in the Examples array SHOULD be in the correct format as specified in the _content_ type.  The `examples` object is mutually exclusive to the `example` object.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
 <a name="contentTypeExample"></a>example | [Example Object](#exampleObject) <span>&#124;</span> [Reference Object](#referenceObject) | Example of the content type.  The example object SHOULD be in the correct format as specified in the _content_ type.  The `example` object is mutually exclusive to the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the the example provided by the schema.
+<a name="contentTypeEncoding"></a>encoding | [Encoding Object](#encodingObject) | Encoding of the content type.  The encoding object SHOULD only apply to `requestBody` objects when the content type is `multipart`.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
@@ -1296,7 +1298,7 @@ schema:
   type: string
   format: base64
 
-# content transfered in binary (octet-stream):
+# content transferred in binary (octet-stream):
 schema:
   type: string
   format: binary
@@ -1346,16 +1348,16 @@ requestBody:
             type: string
             format: uuid
           address:
-            # complex types are stringified to support rfc1866
+            # complex types are stringified to support RFC1866
             type: object
             properties: {}
 ```
 
-Note that in the above example, the contents in the `requestBody` MUST be stringified per RFC1866 when being passed to the server.  In addition, the `address` field complex object will be strigified as well.
+Note that in the above example, the contents in the `requestBody` MUST be stringified per RFC1866 when being passed to the server.  In addition, the `address` field complex object will be stringified as well.
 
 When passing complex objects in the `x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the `parameterContent` section as `form`.
 
-##### Special Considerations for `mutlipart` content
+##### Special Considerations for `multipart` content
 
 It is common to use `multipart/form-data` as a `Content-Type` when transferring request bodies to operations.  In contrast to 2.0, a `schema` is required to define the input parameters to the operation when using `multipart` content.  This allows complex structures as well as supports mechanisms for multiple file uploads.
 
@@ -1398,7 +1400,7 @@ requestBody:
               type: '#/definitions/Address'
 ```
 
-In scenarios where more control is needed over the Content-Type for `multipart` request bodies, an `encoding` attribute is introduced.  This attribute is _only_ applicable to `mulitpart/*` and `x-www-form-urlencoded` request bodies.
+In scenarios where more control is needed over the Content-Type for `multipart` request bodies, an `encoding` attribute is introduced.  This attribute is _only_ applicable to `multipart/*` and `x-www-form-urlencoded` request bodies.
 
 #### <a name="encodingObject"></a>Encoding Object
 
@@ -1449,13 +1451,13 @@ requestBody:
             # default is application/octet-stream, need to declare an image type only!
             type: string
             format: binary
-encoding:
-  historyMetadata:
-    # require XML content-type in utf-8 encoding
-    contentType: application/xml; charset=utf-8
-  profileImage:
-    # only accept png/jpeg
-    contentType: image/png, image/jpeg
+      encoding:
+        historyMetadata:
+          # require XML content-type in utf-8 encoding
+          contentType: application/xml; charset=utf-8
+        profileImage:
+          # only accept png/jpeg
+          contentType: image/png, image/jpeg
 ```
 
 #### <a name="responsesObject"></a>Responses Object
@@ -1699,7 +1701,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
 
 The key used to identify the Path Item Object is a variable expression that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request.
 A simple example might be `$request.body#/url`.
-However, using [variable substition](#variableSubstition) syntax the complete HTTP message can be accessed.
+However, using [variable substitution](#variableSubstitution) syntax the complete HTTP message can be accessed.
 This includes accessing any part of a body that can be accessed using a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901). 
 
 For example, given the following HTTP request:
@@ -1874,7 +1876,7 @@ Because of the potential for name clashes, consider the `href` syntax as the pre
 
 #### <a name="responsePayload"></a>Response Payload Values
 
-Payload values are only available in parseable response payloads which match the advertised media-type and for media-types that can be referenced using a JSON Pointer fragment Id.
+Payload values are only available in parsable response payloads which match the advertised media-type and for media-types that can be referenced using a JSON Pointer fragment Id.
 In all cases, if a value does _not_ exist, the parameter will be considered a `null` value (as opposed to an empty value) and _not_ passed as a parameter to the linked resource.
 In cases where a value is required, and a parameter is not supplied, the client MAY choose to not follow the link definition. 
 
@@ -1917,7 +1919,7 @@ color: ["red", "green", "blue"]
 The variables generated can be used in locations prescribed by the definition.
 
 
-### <a name="variableSubstition"></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:
 
@@ -3337,8 +3339,8 @@ Field Name | Type | Description
 ---|:---:|---|---
 <a name="oauthFlowImplicit"></a>implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow 
 <a name="oauthFlowPassword"></a>password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow 
-<a name="oauthFlowClientCredentials"></a>clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow.  Previously called `application` in OpenApi 2.0. 
-<a name="oauthFlowAuthorizationCode"></a>authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow.  Previously called `accessCode` in OpenApi 2.0. 
+<a name="oauthFlowClientCredentials"></a>clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow.  Previously called `application` in OpenAPI 2.0.
+<a name="oauthFlowAuthorizationCode"></a>authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow.  Previously called `accessCode` in OpenAPI 2.0.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
