Merge branch 'OpenAPI.next' into dm/link-parameters

Author: darrelmiller

versions/3.0.md

@@ -1556,7 +1556,7 @@ 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 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="encodingContentType"></a>contentType | `string` | The Content-Type 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. The value can be a specific media type (e.g. `application/json`), a wildcard media type (e.g. `image/*`), or a comma-separated list of the two types.
 <a name="encodingHeaders"></a>headers | Map[`string`, [Header Object](#headerObject)] | A string map allowing additional information to be provided as headers, for example `Content-Disposition`.  `Content-Type` is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a `multipart`.
 <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 as `query` parameters, including default values. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
 <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 property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
@@ -1683,7 +1683,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 | Map[`string`, [Header Object](#headerObject)  \| [Reference Object](#referenceObject)] |  Maps a header name to its definition. [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored.
-<a name="responseContentObject"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.
+<a name="responseContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.
 <a name="responseLinks"></a>links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject). 
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
@@ -1852,7 +1852,7 @@ Content-Length: 123
 Location: http://example.org/subscription/1
 ```
 
-Here are the examples of how the various expressions evaluate, assuming a the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`.
+The following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`.
 
 Expression | Value 
 ---|:---
@@ -1969,27 +1969,27 @@ schemas:
 The `Link object` represents a possible design-time link for a response.
 The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.
 
-As opposed to _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require that link information be provided in a specific response format at runtime.
+Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response.
 
 For computing links, and providing instructions to execute them, a [runtime expression](#runtimeExpression) is used for accessing values in an operation and using them as parameters while invoking the linked operation.
 
 ##### Fixed Fields
 
 Field Name  |  Type  | Description
 ---|:---:|---
-<a name="linkOperationRef"></a>operationRef | `string` | a relative or absolute reference to an OAS operation. This field is mutually exclusive with the `operationId` field, and MUST point to an [Operation Object](#operationObject).
-<a name="linkOperationId"></a>operationId  | `string` | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.  This field is mutually exclusive with the `operationRef` field.  Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OAS. 
-<a name="linkParameters"></a>parameters   | Map[`string`, Any \| [{expression}](#runtimeExpression)] | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. The parameter name can be qualified using the [parameter location](#parameterIn) `[{in}.]{name}` for operations that use the same parameter name in different locations (e.g. path.id).
+<a name="linkOperationRef"></a>operationRef | `string` | A relative or absolute reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operationObject).
+<a name="linkOperationId"></a>operationId  | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.  This field is mutually exclusive of the `operationRef` field.  Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OAS.
+<a name="linkParameters"></a>parameters   | Map[`string`, Any \| [{expression}](#runtimeExpression) | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation.  The parameter name can be qualified using the [parameter location](#parameterIn) `[{in}.]{name}` for operations that use the same parameter name in different locations (e.g. path.id).
 <a name="linkRequestBody"></a>requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression)] to use as a request body when calling the target operation.
-<a name="linkDescription"></a>description  | `string` | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/).
-<a name="linkServer"></a>server       | [Server Object](#serverObject) | a server object to be used by the target operation.
+<a name="linkDescription"></a>description  | `string` | A description of the link. Supports [CommonMark syntax](http://spec.commonmark.org/).
+<a name="linkServer"></a>server       | [Server Object](#serverObject) | A server object to be used by the target operation.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
 Locating a linked resource MAY be performed by either a `operationRef` or `operationId`.
 In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document.
-Because of the potential for name clashes, consider the `operationRef` syntax as the preferred 
-method for specifications with external references.
+Because of the potential for name clashes, the `operationRef` syntax is preferred 
+for specifications with external references.
 
 ##### Examples
 
@@ -2054,8 +2054,8 @@ links:
       userUuid: $response.body#/uuid
 ```
 
-As with all links, it is at the clients' discretion to follow them, neither 
-permissions nor the ability to make a successful call to that link is guaranteed 
+Clients follow all links at their discretion. 
+Neither permissions, nor the capability to make a successful call to that link, is guaranteed 
 solely by the existence of a relationship.
 
 
@@ -2101,7 +2101,7 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org
       header-reference = "header." token
       query-reference = "query." name  
       path-reference = "path." name
-      body-reference = "body#" fragment
+      body-reference = "body" ["#" fragment]
       fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901)  
       name = *( char )
       char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7)
@@ -2116,21 +2116,16 @@ The table below provides examples of runtime expressions and examples of their u
 
 Source Location | example expression  | notes
 ---|:---|:---|
-HTTP Method            | `$method`         | The allowable values for the `$method` will be those for the HTTP operation 
+HTTP Method            | `$method`         | The allowable values for the `$method` will be those for the HTTP operation.
 Requested media type | `$request.header.accept`        |  
-Request parameter      | `$request.path.id`        | Request parameters MUST be declared in the `parameters` section for the parent operation or they cannot be evaluated.  This includes request headers.
-Request body property   | `$request.body#/user/uuid`   | For operations which accept payloads, references may be made to portions of the `requestBody` or the entire body itself
+Request parameter      | `$request.path.id`        | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers.
+Request body property   | `$request.body#/user/uuid`   | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body.
 Request URL            | `$url`            |  
-Response value         | `$response.body#/status`       |  Only the payload in the response can be accessed with the `$response` syntax.  
+Response value         | `$response.body#/status`       |  In operations which return payloads, references may be made to portions of the response body or the entire body.
 Response header        | `$response.header.Server` |  Single header values only are available
 
 Runtime expressions preserve the type of the referenced value.
-Expression values can be embeded into string values by surrounding the expression with `{}` curly braces.
-
-`$request.body`and `$response.body`expressions are only available in payloads which that can be accessed using a JSON Pointer.
-If a value does _not_ exist, the result of the expression will be considered a `null` value (as opposed to an empty value).
-
-
+Expressions can be embeded into string values by surrounding the expression with `{}` curly braces.
 
 #### <a name="headerObject"></a>Header Object