Callback review and preliminary message expression syntax

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