Merge branch 'OpenAPI.next' into requireed-fields

Ron · web-flow · commit 9dc099c12e01 · 2017-04-25T20:14:25.000-07:00
diff --git a/versions/3.0.md b/versions/3.0.md
@@ -139,7 +139,7 @@ By convention, it is RECOMMENDED that the OpenAPI Specification (OAS) file be na
 
 Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2). 
 Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. 
-`null` is not supported as a value.
+`null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution).
 Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Specification Wright Draft 00.
 
 <a name="dataTypeFormat"></a>Primitives have an optional modifier property: `format`.
@@ -338,7 +338,7 @@ url: https://development.gigantic-server.com/v1
 description: Development server
 ```
 
-The following shows how multiple servers can be described, for example, at the OpenAPI Object's `servers`(#oasServers):
+The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oasServers):
 
 ```yaml
 servers:
@@ -508,7 +508,7 @@ my\org\User
     },
     "petstore_auth": {
       "type": "oauth2",
-      "flow": {
+      "flows": {
         "implicit": {
           "authorizationUrl": "http://example.org/api/oauth/dialog",
           "scopes": {
@@ -576,7 +576,7 @@ components:
       in: header
     petstore_auth:
       type: oauth2
-      flow: 
+      flows: 
         implicit:
           authorizationUrl: http://example.org/api/oauth/dialog
           scopes:
@@ -661,7 +661,7 @@ Field Name | Type | Description
 <a name="pathItemHead"></a>head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path.
 <a name="pathItemPatch"></a>patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path.
 <a name="pathItemTrace"></a>trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path.
-<a name="pathItemServers"></a>servers | [Server Object](#serverObject) | An alternative `server` array to service all operations in this path.  
+<a name="pathItemServers"></a>servers | [[Server Object](#serverObject)] | An alternative `server` array to service all operations in this path.  
 <a name="pathItemParameters"></a>parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. 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).
 
 
@@ -767,7 +767,7 @@ Field Name | Type | Description
 <a name="operationCallbacks"></a>callbacks | [Callbacks Object](#callbacksObject) | The list of possible callbacks as they are returned from executing this operation.
 <a name="operationDeprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.
 <a name="operationSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used.
-<a name="operationServers"></a>servers | [Server Object](#serverObject) | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
+<a name="operationServers"></a>servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
@@ -1111,7 +1111,7 @@ 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="requestBodyContent"></a>content | [Content Object](#contentObject) | **Required.** 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`.
+<a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `false`.
 
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
@@ -1466,7 +1466,7 @@ When passing complex objects in the `x-www-form-urlencoded` content type, the de
 
 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.
 
-When passing in `multipart` types, boundaries MAY be used to separate sections of the content being transferred--thus, the following default `Content-Type`s are defined for `multipart/*`:
+When passing in `multipart` types, boundaries MAY be used to separate sections of the content being transferred — thus, the following default `Content-Type`s are defined for `multipart/*`:
 
 * If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain`
 * If the property is complex, or an array of complex values, the default Content-Type is `application/json`
@@ -1560,7 +1560,7 @@ 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 – `text/plain`; 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 [Parameter Object](#parameterObject) for details on the [`style`](#parameterStyle) property. The behavior follows the same values allowed for `query` parameters, including default values.
+<a name="encodingStyle"></a>style | `string` | Describes how a specific property value will be serialized depending on its type .  See [Parameter Object](#parameterObject) 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). 
@@ -1582,14 +1582,12 @@ SHOULD be the response for a successful operation call.
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-<a name="responsesDefault"></a>default | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | The documentation of responses other than the ones declared for specific HTTP response codes.
-It can be used to cover undeclared responses.
-[Reference Object](#referenceObject) can be used to link to a response that is defined at the [OpenAPI Object's responses](#oasResponses) section.
+<a name="responsesDefault"></a>default | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | The documentation of responses other than the ones declared for specific HTTP response codes. It can be used to cover undeclared responses. [Reference Object](#referenceObject) can be used to link to a response that is defined at the [OpenAPI Object's responses](#oasResponses) section.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="responsesCode"></a>[HTTP Status Code](#httpCodes) | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name (one property per HTTP status code). Describes the expected response for that HTTP status code.  [Reference Object](#referenceObject) can be used to link to a response that is defined at the [OpenAPI Object's responses](#oasResponses) section. This field MUST be quoted for compatibility between JSON and YAML (i.e. "200"), and MAY contain the uppercase character, `X` to designate a wildcard, such as `2XX` to represent all response codes between `[200-299]`.
+<a name="responsesCode"></a>[HTTP Status Code](#httpCodes) | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name (one property per HTTP status code). Describes the expected response for that HTTP status code.  [Reference Object](#referenceObject) can be used to link to a response that is defined at the [OpenAPI Object's responses](#oasResponses) section. This field MUST be quoted for compatibility between JSON and YAML (i.e. '200'), and MAY contain the uppercase character, `X` to designate a wildcard, such as `2XX` to represent all response codes between `[200-299]`. If a response range is defined, and an explicit code within that range is defined as well, the explicit code definition takes precedence over the range definition for that code.
 
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
@@ -1995,8 +1993,7 @@ For computing links, and providing instructions to execute them, [variable subst
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="linkName"></a> {name} | [Link Object](#linkObject) \| [Reference Object](#referenceObject) | A short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject).
-The link SHALL reference a single Link Object, or a JSON Reference to a single link object.
+<a name="linkName"></a> {name} | [Link Object](#linkObject) \| [Reference Object](#referenceObject) | A short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject). The link SHALL reference a single Link Object, or a JSON Reference to a single link object.
 
 #### <a name="linkObject"></a>Link Object
 The `Link Object` is responsible for defining a possible operation based on a single response.
@@ -2655,7 +2652,7 @@ Field Name | Type | Description
 <a name="schemaXml"></a>xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property.
 <a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 
 <a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
-<a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage.
+<a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
@@ -3365,7 +3362,7 @@ Field Name | Type | Validity | Description
 <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. 
+<a name="securitySchemeFlows"></a>flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **Required.** An object containing configuration information for the flow types supported. 
 <a name="securitySchemeOpenIdConnectUrl"></a>openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. 
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
@@ -3423,7 +3420,7 @@ bearerFormat: JWT
 ```json
 {
   "type": "oauth2",
-  "flow": {
+  "flows": {
     "implicit": {
       "authorizationUrl": "https://example.com/api/oauth/dialog",
       "scopes": {
@@ -3437,7 +3434,7 @@ bearerFormat: JWT
 
 ```yaml
 type: oauth2
-flow: 
+flows: 
   implicit:
     authorizationUrl: https://example.com/api/oauth/dialog
     scopes:
@@ -3452,10 +3449,10 @@ Allows configuration of the supported OAuth Flows.
 ##### Fixed Fields
 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="oauthFlowsImplicit"></a>implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow 
+<a name="oauthFlowsPassword"></a>password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow 
+<a name="oauthFlowsClientCredentials"></a>clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow.  Previously called `application` in OpenAPI 2.0.
+<a name="oauthFlowsAuthorizationCode"></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). 
 
@@ -3466,10 +3463,10 @@ Configuration details for a supported OAuth Flow
 ##### Fixed Fields
 Field Name | Type | Validity | Description
 ---|:---:|---|---
-<a name="securitySchemeAuthorizationUrl"></a>authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **Required.** The authorization URL to be used for this flow. This MUST be in the form of a URL.
-<a name="securitySchemeTokenUrl"></a>tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **Required.** The token URL to be used for this flow. This MUST be in the form of a URL.
-<a name="securitySchemeRefreshUrl"></a>refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
-<a name="securitySchemeScopes"></a>scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme.
+<a name="oauthFlowAuthorizationUrl"></a>authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **Required.** The authorization URL to be used for this flow. This MUST be in the form of a URL.
+<a name="oauthFlowTokenUrl"></a>tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **Required.** The token URL to be used for this flow. This MUST be in the form of a URL.
+<a name="oauthFlowRefreshUrl"></a>refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
+<a name="oauthFlowScopes"></a>scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
@@ -3478,7 +3475,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
 ```JSON
 {
   "type": "oauth2",
-  "flow": {
+  "flows": {
     "implicit": {
       "authorizationUrl": "https://example.com/api/oauth/dialog",
       "scopes": {
@@ -3500,7 +3497,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
 
 ```YAML
 type: oauth2
-flow: 
+flows: 
   implicit:
     authorizationUrl: https://example.com/api/oauth/dialog
     scopes:
