clarifications, respond to feedback

Author: fehguy

versions/3.0.md

@@ -1151,6 +1151,8 @@ href      |  url   | a relative or absolute URL to a linked resource. This field
 parameters  | Link Parameters Object | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.
 description | string | a description of the link, supports GFM.
 
+Locating a linked resource may be performed by either a `href` 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 `href` syntax as the preferred method for specifications with external references.
+
 #### <a name="responsePayload"></a>Response Payload Values
 
 Payload values are only available in parseable response payloads which match the advertised media-type.  In all cases, if a value does _not_ exist, the parameter will be considered a `null` value (as opposed to an empty value) and _not_ passed as a parameter to the linked resource. In cases where a value is required, and a parameter is not supplied, the client _may_ choose to not follow the link definition. 
@@ -1194,17 +1196,66 @@ The variables generated can be used in locations prescribed by the definition.
 
 
 ### Variable substitution
-In all cases, _variables_ identified in the response payload may be substitued **only** in locations prescribed in the link definitions.  All such locations are prefixed by a `$response` keyword and surrounded by curly brackets `{}`. 
+In all cases, _variables_ from request and responses may be substituted for link generation.  The table below designates the source of the substitution value and the syntax for accessing it:
 
-### Example
-Computing a link from a response object is performed as follows:
+Source Location | reference identifier | example value | example reference | notes
+---|:---|:---|:---
+HTTP Method            | `$method`         | `/users/{$method}`                | The allowable values for the `$method` will be those for the HTTP operation
+Requested content type | `$accepts`        | `/users/3?format={$accepts}`      |  
+Request parameter      | `$request`        | `/users/{$request.id}`            | Request parameters must be declared in the `parameters` section for the operation or they cannot be used in substitution.  This includes request headers
+Request body           | `$requestBody`    | `/users/{$requestBody.user.uuid}` | For operations which accept payloads, references may be made to portions of the `requestBody` or the entire body itself
+Request URL            | `$url`            | `/track?url={$url}`               | 
+Response value         | `$response`       | `{$response.uuid}`                | Only the payload in the response can be accessed with the `$response` syntax
+Response header        | `$responseHeader` | `{$responseHeader.Server}`        | Single header values only are available.
+
+From the request, the `parameter`s used in calling the operation are made available through the `$request` syntax.  For responses, the response payload may be used with the `$response` syntax.  For both requests and responses, values will be substituted in the link in sections designated with the `$request` or `$response` keyword, surrounded by curly brackets `{}`. 
+
+### Request parameter example
+Computing a link from a request operation like such:
+
+```yaml
+paths:
+  /users/{id}:
+    parameters:
+    - name: id
+      in: path
+      required: true
+      description: the user identifier, as userId or username
+      schema:
+        type: string
+    responses:
+      200:
+        description: the user being returned
+        schema:
+          type: object
+          properties:
+            uuid: the unique user id
+              type: string
+              format: uuid
+```
+
+Can be used in a link like this:
 
 ```yaml
 Addresses:
-  href: /users/{$response.id}/address
+  href: '/users/{$request.id}/department'
+```
+
+Where the `$request.id` is the value passed in the request to `/users/{id}`.  For a `id` value of `10101110`, the generated link would be:
+
+```yaml
+href: '/users/10101110/department'
 ```
 
-Where the `$response.id` from the example above would yield the target:
+### Response payload example
+
+```yaml
+Addresses:
+  href: '/users/{$response.uuid}/address'
+```
+
+Where the `$response.uuid` from the example above would yield the target:
+
 
 ```yaml
 href: '/users/df71a505-07bc-458a-a5c0-73c0340d1ec7/address'
@@ -1225,7 +1276,7 @@ href: 'http://colors.my-server.com/colors/green'
 href: 'http://colors.my-server.com/colors/blue'
 ```
 
-As with all links, it at the the clients' discretion to follow them, and permissions and the existence of a value is not guaranteed soley by the existence of a link relationship. [**I assume you mean that the existance of the link relationship does not guarantee a successful response from the call**]
+As with all links, it at the the clients' discretion to follow them, and permissions and the ability to make a successful call to that link is not guaranteed soley by the existance of a relationship.
 
 
 ### Example