Merge pull request OAI#933 from OAI/earth2marsh-patch-1

Misc errata

Author: webron

versions/3.0.md

@@ -112,7 +112,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**.
 
@@ -217,7 +217,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). 
@@ -583,7 +583,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.
@@ -759,7 +759,7 @@ Field Name | Type | Description
 <a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter 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 parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
 <a name="parameterAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
 <a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.
-<a name="parameterExamples"></a>examples | [[Example Object](#exampleObject)] | Examples of the content type.  Each example in the Examples array SHOULD be in the correct format as specified parameter encoding.  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="parameterExamples"></a>examples | [[Example Object](#exampleObject)] | Examples of the content type.  Each example in the Examples array SHOULD be in the correct format as specified parameter encoding.  The `examples` object is mutually exclusive to the `example` object.  Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL _override_ the example provided by the schema.
 <a name="parameterExample"></a>example | [Example Object](#exampleObject) | Example of the content type.  The example object SHOULD be in the correct format as specified in the parameter encoding.  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 example provided by the the schema.
 
 For more complex scenarios a `content` object can be used to define the media-type 
@@ -937,7 +937,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
@@ -1095,7 +1095,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
 
@@ -1750,7 +1750,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:
 
@@ -1786,7 +1786,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
@@ -1826,7 +1826,7 @@ For a `id` value of `10101110`, the generated link would be:
 href: '/users/10101110/department'
 ```
 
-### Response payload example
+### Response Payload Example
 
 ```yaml
 Addresses:
@@ -3070,7 +3070,7 @@ animals:
 #### <a name="definitionsObject"></a>Definitions Object
 
 An object to hold schemas for data types that can be consumed and produced by operations.
-These data types can be primitives, arrays or models.
+These data types can be primitives, arrays, or models.
 
 ##### Patterned Fields
 
@@ -3296,7 +3296,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. 
@@ -3549,7 +3549,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.