Grammar fixes copied from Kris' PRs
MODIFY
versions/3.0.md
versions/3.0.md
@@ -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,7 +1969,7 @@ 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.
@@ -1977,18 +1977,18 @@ For computing links, and providing instructions to execute them, a [runtime expr
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="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.
-<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
@@ -2053,8 +2053,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.
@@ -2100,7 +2100,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)
@@ -2115,21 +2115,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

Grammar fixes copied from Kris' PRs