added full example, link

Author: fehguy

examples/v3.0/callback-example.yaml

@@ -0,0 +1,56 @@
+paths:
+  /streams:
+    post:
+      description: subscribes a client to receive out-of-band data
+      parameters:
+        - name: callbackUrl
+          in: query
+          required: true
+          description: |
+            the ___location where data will be sent.  Must be network accessible
+            by the source server
+          schema:
+            type: string
+            format: uri
+            example: https://tonys-server.com
+      responses:
+        201:
+          description: subscription successfully created
+          content:
+            application/json:
+              schema:
+                description: subscription information
+                required:
+                  - subscriptionId
+                properties:
+                  subscriptionId:
+                    description: this unique identifier allows management of the subscription
+                    type: string
+                    example: 2531329f-fb09-4ef7-887e-84e648214436
+      callbacks:
+        # the name `onData` is a convenience locator
+        onData:
+          # when data is sent, it will be sent to the `callbackUrl` provided
+          # when making the subscription PLUS the suffix `/data`
+          $request.query.callbackUrl/data:
+            post:
+              requestBody:
+                description: subscription payload
+                content:
+                  application/json:
+                    schema:
+                      properties:
+                        timestamp:
+                          type: string
+                          format: date-time
+                        userData:
+                          $ref: '#/components/schemas/UserLogData'
+              responses:
+                202:
+                  description: |
+                    Your server implementation should return this HTTP status code
+                    if the data was received successfully
+                204:
+                  description: |
+                    Your server should return this HTTP status code if no longer interested
+                    in further updates

versions/3.0.md

@@ -1728,7 +1728,7 @@ The key value used to identify the callback object is an expression, evaluated a
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) | A Path Item Object used to define a callback request and expected responses.
+<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) | A Path Item Object used to define a callback request and expected responses.  A full example may be found at https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/examples/v3.0/callback-example.yaml
 
 This object can be extended with [Specification Extensions](#specificationExtensions).