Updates to Callback/Links based on meeting
MODIFY
versions/3.0.md
versions/3.0.md
@@ -1575,7 +1575,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
##### Key Expression
The key used to identify the callback object is a variable expression that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request.
-A simple example might be "$request.body(/url)".
+A simple example might be `$request.body#/url`.
However, using [variable substition](#variableSubstition) syntax the complete HTTP message can be accessed.
This includes accessing any part of a body that can be accessed using a JSONPointer [RFC6901](https://tools.ietf.org/html/rfc6901).
@@ -1611,8 +1611,8 @@ $method | POST
$request.path.eventType | myevent
$request.query.queryUrl | http://clientdomain.com/stillrunning
$request.header.content-Type | application/json
-$request.body(/failed) | http://clientdomain.com/stillrunning
-$request.body(/successurls/2) | http://clientdomain.com/medium
+$request.body#/failed | http://clientdomain.com/stillrunning
+$request.body#/successurls/2 | http://clientdomain.com/medium
$response.header.Location | http://example.org/subscription/1
@@ -1623,7 +1623,7 @@ A callback to the URL specified by the `url` parameter in the request
```yaml
myWebhook:
- '$request.body(/url)':
+ '$request.body#/url':
post:
requestBody:
description: Callback payload
@@ -1735,11 +1735,11 @@ The `Link Object` is responsible for defining a possible operation based on a si
Field Name | Type | Description
---|:---:|---
-href | url | 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.
-parameters | Link Parameters Object | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.
-headers | Link Headers Object | 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/).
+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.
+parameters | [Link Parameters Object](#linkParameters) | 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/).
This object can be extended with [Specification Extensions](#specificationExtensions).
@@ -1749,7 +1749,7 @@ Because of the potential for name clashes, consider the `href` syntax as the pre
#### <a name="responsePayload"></a>Response Payload Values
-Payload values are only available in parseable response payloads which match the advertised media-type and for media-types that can map to the object/array/property model syntax used by variable expressions.
+Payload values are only available in parseable 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.
@@ -1801,10 +1801,10 @@ Source Location | variable expression | example reference | notes
HTTP Method | `$method` | `/users/{$method}` | The allowable values for the `$method` will be those for the HTTP operation
Requested content type | `$request.header.accept` | `/users/3?format={$request.header.accept}` |
Request parameter | `$request.path.id` | `/users/{$request.path.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 | `$request.body` | `/users/{$request.body(/user/uuid)}` | For operations which accept payloads, references may be made to portions of the `requestBody` or the entire body itself
+Request body | `$request.body` | `/users/{$request.body#/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.body` | `{$response.body(/uuid)}` | Only the payload in the response can be accessed with the `$response` syntax.
-Response header | `$response.header` | `{$response.header.Server}` |
+Response value | `$response.body` | `{$response.body#/uuid}` | Only the payload in the response can be accessed with the `$response` syntax.
+Response header | `$response.header` | `{$response.header.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.
@@ -1818,8 +1818,8 @@ The variable expression is defined by the following [ABNF](https://tools.ietf.or
header-reference = "header." token
query-reference = "query." name
path-reference = "path." name
- body-reference = "body(" fragment ")"
- fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901) with any instances of `(` or `)` escaped
+ 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)
token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6)
@@ -1872,7 +1872,7 @@ href: '/users/10101110/department'
```yaml
Addresses:
- href: '/users/{$response.body(/uuid)}/address'
+ href: '/users/{$response.body#/uuid}/address'
```
Where the `$response.uuid` from the example above would yield the target:
@@ -1886,7 +1886,7 @@ And the array example:
```yaml
ColorSelection:
- href: 'http://colors.my-server.com/colors/{$response.body(/color)}'
+ href: 'http://colors.my-server.com/colors/{$response.body#/color}'
```
Would produce the following links:
@@ -2044,26 +2044,26 @@ components:
# returns array of '#/components/definitions/repository'
operationId: getRepositoriesByOwner
parameters:
- username: $response.body(/username)
+ username: $response.body#/username
UserRepository:
# returns '#/components/definitions/repository'
operationId: getRepository
parameters:
- username: $response.body(/owner/username)
- slug: $response.body.slug
+ username: $response.body#/owner/username
+ slug: $response.body#/slug
RepositoryPullRequests:
# returns '#/components/definitions/pullrequest'
operationId: getPullRequestsByRepository
params:
- username: $response.body(/owner/username)
- slug: $response.body(/slug)
+ username: $response.body#/owner/username
+ slug: $response.body#/slug
PullRequestMerge:
# executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge
operationId: mergePullRequest
parameters:
- username: $response.body(/user/username) # Should be $response.author.username?
- slug: $response.body(/repository/slug)
- pid: $response.body(/id)
+ username: $response.body#/user/username # Should be $response.author.username?
+ slug: $response.body#/repository/slug
+ pid: $response.body#/id
definitions:
user:
type: object
@@ -2099,7 +2099,7 @@ components:
links:
UserRepositories:
# returns array of '#/components/definitions/repository'
- href: '/2.0/repositories/{$response.body(/username)}'
+ href: '/2.0/repositories/{$response.body#/username}'
```
or an absolute `href`:
@@ -2109,11 +2109,11 @@ components:
links:
UserRepositories:
# returns array of '#/components/definitions/repository'
- href: 'https://na2.gigantic-server.com/2.0/repositories/{$response.body(/username)}'
+ href: 'https://na2.gigantic-server.com/2.0/repositories/{$response.body#/username}'
```
-### Link Parameters
+### <a name="linkParameters"></a>Link Parameters
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.
Many operations require parameters to be passed, and these may be dynamic depending on the response itself.
@@ -2141,7 +2141,7 @@ components:
UserCommitHistory:
operationId: userCommitHistory
parameters:
- username: $response.body(/user/username)
+ username: $response.body#/user/username
page: 0
```

Updates to Callback/Links based on meeting