From 94baeb8165e64ccd0c364801c28d473770983f86 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=20M=C3=A9ndez?= <fmvilas@gmail.com>
Date: Tue, 20 Oct 2020 16:52:30 +0200
Subject: [PATCH] Clarify message examples definition (#453)

* Clarify message examples definition

* Update versions/2.0.0/asyncapi.md

Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com>

* Add links to headers and payload and clarify examples should validate against definitions

* Add JSON Schema definition of examples

Co-authored-by: Lukasz Gornicki <lpgornicki@gmail.com>
---
 versions/2.0.0/asyncapi.md | 27 ++++++++++++++++++++++++++-
 versions/2.0.0/schema.json |  9 ++++++++-
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/versions/2.0.0/asyncapi.md b/versions/2.0.0/asyncapi.md
index fdfd06dc..0c8b528b 100644
--- a/versions/2.0.0/asyncapi.md
+++ b/versions/2.0.0/asyncapi.md
@@ -1003,7 +1003,7 @@ Field Name | Type | Description
 <a name="messageObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of messages.
 <a name="messageObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message.
 <a name="messageObjectBindings"></a>bindings | [Message Bindings Object](#messageBindingsObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message.
-<a name="messageObjectExamples"></a>examples | [Map[`string`, `any`]] | An array with examples of valid message objects.
+<a name="messageObjectExamples"></a>examples | [Map[`string`, `any`]] | An array of key/value pairs where keys MUST be either **headers** and/or **payload**. Values MUST contain examples that validate against the [headers](#messageObjectHeaders) or [payload](#messageObjectPayload) fields, respectively.
 <a name="messageObjectTraits"></a>traits | [[Message Trait Object](#messageTraitObject) &#124; [Reference Object](#referenceObject)] | A list of traits to apply to the message object. Traits MUST be merged into the message object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Message Object](#messageObject).
 
 This object can be extended with [Specification Extensions](#specificationExtensions).
@@ -1070,6 +1070,22 @@ Name | Allowed values | Notes
   },
   "traits": [
     { "$ref": "#/components/messageTraits/commonHeaders" }
+  ],
+  "examples": [
+    {
+      "headers": {
+        "correlationId": "my-correlation-id",
+        "applicationInstanceId": "myInstanceId"
+      },
+      "payload": {
+        "user": {
+          "someUserKey": "someUserValue"
+        },
+        "signup": {
+          "someSignupKey": "someSignupValue"
+        }
+      }
+    }
   ]
 }
 ```
@@ -1105,6 +1121,15 @@ correlationId:
   location: $message.header#/correlationId
 traits:
   - $ref: "#/components/messageTraits/commonHeaders"
+examples:
+  - headers:
+      correlationId: my-correlation-id
+      applicationInstanceId: myInstanceId
+    payload:
+      user:
+        someUserKey: someUserValue
+      signup:
+        someSignupKey: someSignupValue
 ```
 
 Example using Avro to define the payload:
diff --git a/versions/2.0.0/schema.json b/versions/2.0.0/schema.json
index cd3f359f..286ae4bc 100644
--- a/versions/2.0.0/schema.json
+++ b/versions/2.0.0/schema.json
@@ -690,7 +690,14 @@
                 "examples": {
                   "type": "array",
                   "items": {
-                    "type": "object"
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "headers": {
+                        "type": "object"
+                      },
+                      "payload": {}
+                    }
                   }
                 },
                 "bindings": {