Callback review and preliminary message expression syntax
MODIFY
versions/3.0.md
versions/3.0.md
@@ -1555,15 +1555,70 @@ description: object created
#### <a name="callbackObject"></a>Callback Object
-A container for possible out-of band callbacks from an operation. A callback may be returned from an operation, calling back to the path specified in the operation object.
+A map of possible out-of band callbacks related to the parent operation. Each value in the map is an [operation object](#operationObject) that describes a request that may be initiated by the API provider and the responses expected. The key value used to identify callback object is an expression, that when evaluated at runtime, identifies a URL to used for the callback operation.
##### Patterned Fields
Field Pattern | Type | Description
---|:---:|---
-<a name="responseName"></a>Callback name | [Callback Operation Object](#operationObject) <span>&#124;</span> [Operation Object](#operationObject) | An operation object used to define a callback payload structure
+<a name="responseName"></a>Callback name | [Callback Operation Object](#operationObject) <span>&#124;</span> [Operation Object](#operationObject) | An operation object used to define a callback request and expected responses
This object can be extended with [Specification Extensions](#specificationExtensions).
+##### Key Expression
+
+The key used to identify the callback object is also an expression that can be evaluated on the runtime HTTP request/response to identify the URL to be used for the callback request. A simple example might be "$request.body.url". However, the expression syntax enables accessing the complete HTTP message and reaching into any payload that can map to an object/array/property data model.
+
+The expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax
+
+```
+ expression = target source *( "." bind-token [ index ]] )
+ target = ("$request." | "$response.")
+ source = ( header-reference | query-reference | path-reference | body-reference )
+ header-reference = "header." token
+ query-reference = "query." name
+ path-reference = "path." name
+ body-reference = "body" *( index | "." name )
+ index = "[" *(digit) "]"
+ 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)
+```
+
+The `name` identifier is case-sensitive, whereas `token` is not.
+
+Given the following HTTP request:
+
+```http
+POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1
+Host: example.org
+Content-Type: application/json
+Content-Length: 123
+
+{
+ "failedurl" : "http://clientdomain.com/failed"
+ "successurls : [
+ "http://clientdomain.com/fast",
+ "http://clientdomain.com/medium",
+ "http://clientdomain.com/slow"
+ ]
+}
+
+201 Created
+Location: http://example.org/subscription/1
+
+```
+
+Here are the examples of how the various expressions evaluate, assuming a the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`.
+
+Expression | Value
+---|:---
+$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
+$response.header.Location | http://example.org/subscription/1
+
##### Callback Object Example
@@ -1572,7 +1627,7 @@ A callback to the URL specified by the `url` parameter in the request
```yaml
myWebhook:
- '$request.url':
+ '$request.body.url':
post:
body:
name: postResponse

Callback review and preliminary message expression syntax