From 3f72b7ad3ffa9d504e4dd8d058080e2ff3765a54 Mon Sep 17 00:00:00 2001
From: Tony Tam <fehguy@gmail.com>
Date: Thu, 15 Jun 2017 07:18:23 -0700
Subject: [PATCH 1/3] added full example, link

---
 examples/v3.0/callback-example.yaml | 56 +++++++++++++++++++++++++++++
 versions/3.0.md                     |  2 +-
 2 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 examples/v3.0/callback-example.yaml

diff --git a/examples/v3.0/callback-example.yaml b/examples/v3.0/callback-example.yaml
new file mode 100644
index 0000000000..8db4568022
--- /dev/null
+++ b/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
diff --git a/versions/3.0.md b/versions/3.0.md
index d83f57acce..81e464930b 100644
--- a/versions/3.0.md
+++ b/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). 
 

From e459cb18cdc506fd8f778ba10d6e49a7db14d2f2 Mon Sep 17 00:00:00 2001
From: Tony Tam <tony@eatbacon.org>
Date: Thu, 15 Jun 2017 08:03:19 -0700
Subject: [PATCH 2/3] Quoted numeric keys

---
 examples/v3.0/callback-example.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/v3.0/callback-example.yaml b/examples/v3.0/callback-example.yaml
index 8db4568022..54c310eb01 100644
--- a/examples/v3.0/callback-example.yaml
+++ b/examples/v3.0/callback-example.yaml
@@ -46,11 +46,11 @@ paths:
                         userData:
                           $ref: '#/components/schemas/UserLogData'
               responses:
-                202:
+                '202':
                   description: |
                     Your server implementation should return this HTTP status code
                     if the data was received successfully
-                204:
+                '204':
                   description: |
                     Your server should return this HTTP status code if no longer interested
                     in further updates

From 406e63adc86553da9a6f2cd3f6e1b63f3e37b068 Mon Sep 17 00:00:00 2001
From: "Rob Dolin (MSFT)" <robdolin@microsoft.com>
Date: Thu, 15 Jun 2017 09:09:13 -0700
Subject: [PATCH 3/3] Create callback-example.yaml

---
 examples/v3.0/callback-example.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/v3.0/callback-example.yaml b/examples/v3.0/callback-example.yaml
index 54c310eb01..426ee39a76 100644
--- a/examples/v3.0/callback-example.yaml
+++ b/examples/v3.0/callback-example.yaml
@@ -14,7 +14,7 @@ paths:
             format: uri
             example: https://tonys-server.com
       responses:
-        201:
+        '201':
           description: subscription successfully created
           content:
             application/json: