Updates to link object and link parameter objects

Author: darrelmiller

versions/3.0.md

@@ -1860,25 +1860,20 @@ The presence of a link does not guarantee the caller's ability to successfully i
 
 As opposed to _dynamic_ links (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.
 
-For computing links, and providing instructions to execute them, a mechanism is defined for accessing values in a response and using them as variables while invoking the linked operation.
-
-Field Name | Type | Description
----|:---:|---
-<a name="referenceRef"></a>$ref | `string` | If present, a reference to another Links Object.  Note, the presence of `$ref` in the Links Object will cause all _Patterned Objects_ to be ignored. 
+For computing links, and providing instructions to execute them, [variable substitution](#variableSubstitution) is used for accessing values in a response and using them as values while invoking the linked operation.
 
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="linkName"></a>link name | [Link Object](#linkObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject).
+<a name="linkName"></a> {name} | [Link Object](#linkObject) <span>&#124;</span> [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.
 
 Field Name  |  Type  | Description
 ---|:---:|---
 href        | `string`    | a relative or absolute URL to a linked resource. This field is mutually exclusive with the `operationId` field.
-operationId | `string` | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.  This field is mutually exclusive with the `href` field.  Relative `href` values MAY be used to locate an existing Operation Object in the OAS.
+operationId | `string` | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.  This field is mutually exclusive with the `href` field.  Relative `href` values MAY be used to locate an existing [Operation Object](#operationObject) in the OAS.
 parameters  | [Link Parameters Object](#linkParametersObject) | an object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.
 headers     | [Headers Object](#headersObject)    | an object representing headers to pass to the linked resource. Where conflicts occur between these headers, and those defined in the related operation, these headers override.
 description | `string` | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/).
@@ -2053,9 +2048,10 @@ paths:
       operationId: getUserByName
       parameters: 
       - name: username
-        type: string
         in: path
         required: true
+        schema:
+          type: string
       responses: 
         200: 
           description: The User
@@ -2071,9 +2067,10 @@ paths:
       operationId: getRepositoriesByOwner
       parameters:
         - name: username
-          type: string
           in: path
           required: true
+          schema:
+            type: string
       responses:
         200:
           description: repositories owned by the supplied user
@@ -2094,10 +2091,13 @@ paths:
           type: string
           in: path
           required: true
+          schema:
+            type: string
         - name: slug
-          type: string
           in: path
           required: true
+          schema:
+            type: string
       responses: 
         200:
           description: The repository
@@ -2113,20 +2113,23 @@ paths:
       operationId: getPullRequestsByRepository
       parameters: 
       - name: username
-        type: string
         in: path
         required: true
+        schema:
+          type: string
       - name: slug
-        type: string
         in: path
         required: true
+        schema:
+          type: string
       - name: state
-        type: string
         in: query
-        enum: 
-          - open
-          - merged
-          - declined
+        schema:
+          type: string
+          enum: 
+            - open
+            - merged
+            - declined
       responses: 
         200: 
           description: an array of pull request objects
@@ -2141,17 +2144,20 @@ paths:
       operationId: getPullRequestsById
       parameters: 
       - name: username
-        type: string
         in: path
         required: true
+        schema:
+          type: string
       - name: slug
-        type: string
         in: path
         required: true
+        schema:
+          type: string
       - name: pid
-        type: string
         in: path
         required: true
+        schema:
+          type: string
       responses: 
         200: 
           description: a pull request object
@@ -2166,17 +2172,20 @@ paths:
       operationId: mergePullRequest
       parameters: 
       - name: username
-        type: string
         in: path
         required: true
+        schema:
+          type: string
       - name: slug
-        type: string
         in: path
         required: true
+        schema:
+          type: string
       - name: pid
-        type: string
         in: path
         required: true
+        schema:
+          type: string
       responses: 
         204:
           description: the PR was successfully merged
@@ -2262,6 +2271,10 @@ Many operations require parameters to be passed, and these MAY be dynamic depend
 To specify parameters required by the operation, we can use a **Link Parameters Object**.
 This object contains parameter names along with static or dynamic values:
 
+Field Pattern | Type | Description
+---|:---:|---
+<a name="linkParameterName"></a> {name} | Any <span>&#124;</span> [{expression}](#variableSubstitution) | A constant value or expression to be evaluated and passed to the linked operation.
+
 ```yaml
 paths:
   /user/{username}: # ...