addresses feedback from OAI/TDC call
MODIFY
versions/3.0.md
versions/3.0.md
@@ -1868,8 +1868,8 @@ The `Link Object` is responsible for defining a possible operation based on a si
Field Name | Type | Description
---|:---:|---
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 `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`.
+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
@@ -1883,9 +1883,11 @@ 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
@@ -1992,51 +1994,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:
@@ -2209,7 +2206,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:
@@ -2240,26 +2237,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.

addresses feedback from OAI/TDC call