added full example, link
ADD
examples/v3.0/callback-example.yaml
+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

MODIFY
versions/3.0.md
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).

added full example, link