Merge pull request OAI#1040 from OAI/issue-1039

Explanation for links confusion, fixes

Author: fehguy

versions/3.0.md

@@ -2003,23 +2003,27 @@ The `Link Object` is responsible for defining a possible operation based on a si
 
 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](#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/).
+operationRef | `string` | a relative or absolute reference to an OAS operation. This field is mutually exclusive with the `operationId` field, and must point to the fragment of a valid OAS definition
+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.
+parameters   | [Link Parameters Object](#linkParametersObject) | an object representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`.
+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/).
+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 `href` or `operationId`.
+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 `href` syntax as the preferred method for specifications with external references.
+Because of the potential for name clashes, consider the `operationRef` syntax as the preferred 
+method for specifications with external references.
 
 ##### <a name="responsePayload"></a>Response Payload Values
 
-Payload values are only available in parsable response payloads which match the advertised media type and for media types that can be referenced using a JSON Pointer fragment Id.
-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. 
+Payload values are only available in parsable response payloads which match the advertised media 
+type and for media types that can be referenced using a JSON Pointer fragment Id.  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. 
 
 ##### Example
 
@@ -2126,51 +2130,46 @@ Can be used in a link like this:
 
 ```yaml
 Addresses:
-  href: '/users/{$request.path.id}/department'
+  # the target link operationId
+  operationId: getUserAddress
+  parameters:
+    # get the `id` field from the request path parameter named `id`
+    userId: '{$request.path.id}'
 ```
 
 Where the `$request.path.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'
-```
 
 ##### Response Payload Example
 
 ```yaml
 Addresses:
-  href: '/users/{$response.body#/uuid}/address'
-```
-
-Where the `$response.uuid` from the example above would yield the target:
-
-
-```yaml
-href: '/users/df71a505-07bc-458a-a5c0-73c0340d1ec7/address'
+  operationId: getUserAddressByUUID
+  parameters:
+    # get the `id` field from the request path parameter named `id`
+    userUuid: '{$response.body#/uuid}'
 ```
 
 And the array example:
 
 ```yaml
 ColorSelection:
-  href: 'http://colors.my-server.com/colors/{$response.body#/color}'
+  operationId: getColorSample
+  parameters:
+    colorName: '{$response.body#/color}'
 ```
 
-Would produce the following links:
-
-```yaml
-href: 'http://colors.my-server.com/colors/red'
-href: 'http://colors.my-server.com/colors/green'
-href: 'http://colors.my-server.com/colors/blue'
-```
+Would produce three links with the `colorName` of `red`, `green`, and `blue`:
 
-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 solely by the existence of a relationship.
+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 
+solely by the existence of a relationship.
 
 
 ##### Example
 
-The example below shows how relationships in the BitBucket API can be represented with the link schema. This example uses `operationId` values to link responses to possible operations.
+The example below shows how relationships in the BitBucket API can be represented 
+with the link schema. This example uses `operationId` values to link responses to 
+possible operations.
 
 ```yaml
 paths: 
@@ -2343,7 +2342,7 @@ components:
       # executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge
       operationId: mergePullRequest
       parameters:
-        username: $response.body#/user/username # Should be $response.author.username?
+        username: $response.body#/author/username
         slug: $response.body#/repository/slug
         pid: $response.body#/id
   schemas: 
@@ -2374,26 +2373,29 @@ components:
           $ref: '#/components/schemas/user'
 ```
 
-As references to `operationId` MAY NOT be possible (the `operationId` is an optional value), references MAY also be made through a relative `href`:
+As references to `operationId` MAY NOT be possible (the `operationId` is an optional 
+value), references MAY also be made through a relative `operationRef`:
 
 ```yaml
 components:
   links:
     UserRepositories:
       # returns array of '#/components/schemas/repository'
-      href: '/2.0/repositories/{$response.body#/username}'
+      operationRef: '#paths~12.0~1repositories~1{$response.body#/username}'
 ```
 
-or an absolute `href`:
+or an absolute `operationRef`:
 
 ```yaml
 components:
   links:
     UserRepositories:
       # returns array of '#/components/schemas/repository'
-      href: 'https://na2.gigantic-server.com/2.0/repositories/{$response.body#/username}'
+      href: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{$response.body#/username}'
 ```
 
+Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when 
+using JSON references.
 
 #### <a name="linkParametersObject"></a>Link Parameters Object
 Using the `operationId` to reference an operation in the definition has many benefits, including the ability to define media type options, security requirements, response and error payloads.