Merge pull request #1219 from OAI/dm/redo-grammar

Grammar fixes copied from Kris' PRs

Author: webron

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,26 +1969,26 @@ 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.
-<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="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.
 
 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