From d0ed8eb7be541f184949b3548ae8cc9288bb5e18 Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Mon, 3 Jul 2023 23:30:21 +0530
Subject: [PATCH 01/21] initial draft for payload schema

---
 .../concepts/asyncapi-document/_section.md    |   4 +
 .../docs/concepts/asyncapi-document/index.md  |  12 +++
 .../asyncapi-document/payload-schema.md       | 100 ++++++++++++++++++
 3 files changed, 116 insertions(+)
 create mode 100644 pages/docs/concepts/asyncapi-document/_section.md
 create mode 100644 pages/docs/concepts/asyncapi-document/index.md
 create mode 100644 pages/docs/concepts/asyncapi-document/payload-schema.md

diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md
new file mode 100644
index 00000000000..29113941ca0
--- /dev/null
+++ b/pages/docs/concepts/asyncapi-document/_section.md
@@ -0,0 +1,4 @@
+---
+title: Home
+weight: 0
+---
\ No newline at end of file
diff --git a/pages/docs/concepts/asyncapi-document/index.md b/pages/docs/concepts/asyncapi-document/index.md
new file mode 100644
index 00000000000..b662bbad41c
--- /dev/null
+++ b/pages/docs/concepts/asyncapi-document/index.md
@@ -0,0 +1,12 @@
+---
+title: Welcome
+weight: 0
+---
+
+## Welcome to AsyncAPI Docs!
+
+AsyncAPI is an open source initiative that seeks to improve the current state of Event-Driven Architectures (EDA).
+
+- Payload schema
+
+---
diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
new file mode 100644
index 00000000000..f87f5c7d6ab
--- /dev/null
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -0,0 +1,100 @@
+---
+title: Payload Schema
+weight: 139
+---
+
+The payload schema defines the format, data types, and properties of a message's payload. It ensures that the payload follows a specific structure and data format.
+
+In the AsyncAPI specification, the payload schema is created using schema languages like JSON or Avro Schema. This allows consumers of the specification to understand the payload's structure and data types.
+
+For complex messages and structured data models, Avro schemas are recommended as they support complex types such as arrays and records. Avro schemas can be created by directly writing the JSON representation or by using tools like Avro4s UI to generate the schema from valid JSON.
+
+## Prerequisites:
+
+Install the necessary dependencies:
+Use npm or yarn to install the @asyncapi/avro-schema-parser package. This package enables Avro schema parsing in AsyncAPI.
+
+To send complex messages with payload added using Avro schemas in AsyncAPI, follow these steps:
+
+## Define Avro schema
+
+Define the Avro schema for the message payload: You can choose one of the following methods:
+
+- Embedded notation: Define the Avro schema within the message payload property.
+- Remote reference: Specify the schema using an absolute remote endpoint, such as $ref: 'https://schemas.example.com/user'.
+- Local reference: Specify the schema using a relative reference, such as $ref: './user-signedup.avsc#/User'.
+
+Here is an example of an AsyncAPI specification file that uses the local reference method:
+
+```yaml
+asyncapi: '2.0.0'
+id: 'urn:example.user'
+channels:
+  user/signedup:
+    subscribe:
+      contentType: avro/binary
+      schemaFormat: application/vnd.apache.avro+json;version=1.9.0
+      payload:
+        $ref: './user.avsc#/User'
+```
+
+Create a separate Avro schema file with a .avsc extension. This file should define the structure of the message payload. Here is an example of an Avro schema file for the User record type:
+
+```json
+{
+  "namespace": "example.avro",
+  "type": "record",
+  "name": "User",
+  "fields": [
+    { "name": "fullName", "type": "string" },
+    { "name": "email", "type": "string" },
+    { "name": "age", "type": "int" }
+  ]
+}
+```
+
+## Attach examples to the AsyncAPI specification:
+
+Although optional, it is highly recommended to attach examples to the AsyncAPI specification. For a binary encoding like Avro, you can use JSON or YAML format. Attach the examples to the examples property within the message payload definition. Here is an example:
+
+```yaml
+asyncapi: '2.0.0'
+id: 'urn:io.example'
+channels:
+  user/signedup:
+    subscribe:
+      examples:
+        - laurent:
+            payload: |-
+              {"fullName": "Demo", "email": "demo@demo.io", "age": 19}
+```
+
+You can use a Schema Registry to separate the Avro schema from the message payload, making it easier to manage schema compatibility.
+
+## Reuse schema from components
+
+To reuse a schema in your AsyncAPI specification, define it in the components/schemas section and reference it using the $ref keyword. This approach helps avoid duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI.
+
+```yaml
+asyncapi: '2.0.0'
+info:
+  title: My AsyncAPI Specification
+  version: '1.0.0'
+channels:
+  user/signedup:
+    subscribe:
+      message:
+        payload:
+          $ref: '#/components/schemas/User'
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        fullName:
+          type: string
+        email:
+          type: string
+        age:
+          type: integer
+```

From df0a8ab9e516d7774fa15c74a77d70e43eabf517 Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Tue, 11 Jul 2023 11:32:59 +0530
Subject: [PATCH 02/21] peer feedback

---
 .../concepts/asyncapi-document/_section.md    |  4 +--
 .../docs/concepts/asyncapi-document/index.md  | 12 -------
 .../asyncapi-document/payload-schema.md       | 35 ++++++++++++-------
 3 files changed, 24 insertions(+), 27 deletions(-)
 delete mode 100644 pages/docs/concepts/asyncapi-document/index.md

diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md
index 29113941ca0..9ee6204f423 100644
--- a/pages/docs/concepts/asyncapi-document/_section.md
+++ b/pages/docs/concepts/asyncapi-document/_section.md
@@ -1,4 +1,4 @@
 ---
-title: Home
+title: AsyncAPI-document
 weight: 0
----
\ No newline at end of file
+---
diff --git a/pages/docs/concepts/asyncapi-document/index.md b/pages/docs/concepts/asyncapi-document/index.md
deleted file mode 100644
index b662bbad41c..00000000000
--- a/pages/docs/concepts/asyncapi-document/index.md
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: Welcome
-weight: 0
----
-
-## Welcome to AsyncAPI Docs!
-
-AsyncAPI is an open source initiative that seeks to improve the current state of Event-Driven Architectures (EDA).
-
-- Payload schema
-
----
diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index f87f5c7d6ab..d5adc7dd1a4 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -3,18 +3,13 @@ title: Payload Schema
 weight: 139
 ---
 
-The payload schema defines the format, data types, and properties of a message's payload. It ensures that the payload follows a specific structure and data format.
+The payload schema defines the format, data types, and properties of a message's payload. To ensure that the payload follows a specific structure and data format.
 
-In the AsyncAPI specification, the payload schema is created using schema languages like JSON or Avro Schema. This allows consumers of the specification to understand the payload's structure and data types.
+In the AsyncAPI specification, you can use schema languages such as JSON or Avro Schema to create the payload schema. Enabling consumers to gain insights into the structure and data types of the payload.
 
-For complex messages and structured data models, Avro schemas are recommended as they support complex types such as arrays and records. Avro schemas can be created by directly writing the JSON representation or by using tools like Avro4s UI to generate the schema from valid JSON.
+To handle complex messages and structured data models, you should use Avro schemas. Avro schemas support complex types like arrays and records. You can create Avro schemas by writing the JSON representation or by utilising tools like Avro4s UI to generate the schema from valid JSON.
 
-## Prerequisites:
-
-Install the necessary dependencies:
-Use npm or yarn to install the @asyncapi/avro-schema-parser package. This package enables Avro schema parsing in AsyncAPI.
-
-To send complex messages with payload added using Avro schemas in AsyncAPI, follow these steps:
+Use npm or yarn to install the `@asyncapi/avro-schema-parser` package to enable Avro schema parsing in AsyncAPI.
 
 ## Define Avro schema
 
@@ -38,7 +33,7 @@ channels:
         $ref: './user.avsc#/User'
 ```
 
-Create a separate Avro schema file with a .avsc extension. This file should define the structure of the message payload. Here is an example of an Avro schema file for the User record type:
+Create a separate Avro schema file with a .avsc extension. The file should define the structure of the message payload. Here is an example of an Avro schema file for the User record type:
 
 ```json
 {
@@ -53,7 +48,21 @@ Create a separate Avro schema file with a .avsc extension. This file should defi
 }
 ```
 
-## Attach examples to the AsyncAPI specification:
+```mermaid
+graph LR
+A[Define Avro Schema]
+B[Local Reference]
+C[Avro Schema File]
+D[Message Payload]
+E[AsyncAPI Specification File]
+
+A -->|One of the following methods:| B
+B -->|Specify schema using relative reference| D
+E -->|Uses local reference method| C
+C-->|Defines structure of message payload| D
+```
+
+## Attach examples
 
 Although optional, it is highly recommended to attach examples to the AsyncAPI specification. For a binary encoding like Avro, you can use JSON or YAML format. Attach the examples to the examples property within the message payload definition. Here is an example:
 
@@ -71,9 +80,9 @@ channels:
 
 You can use a Schema Registry to separate the Avro schema from the message payload, making it easier to manage schema compatibility.
 
-## Reuse schema from components
+## Reuse schema
 
-To reuse a schema in your AsyncAPI specification, define it in the components/schemas section and reference it using the $ref keyword. This approach helps avoid duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI.
+To reuse a schema in your AsyncAPI specification, define it in the components/schemas section and reference it using the $ref keyword. Using $ref helps to avoid duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI.
 
 ```yaml
 asyncapi: '2.0.0'

From deb4487fdbb5632ef218b93137ca3a58025acd42 Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Tue, 11 Jul 2023 12:22:37 +0530
Subject: [PATCH 03/21]  fix formatting

---
 .../asyncapi-document/payload-schema.md       | 28 +++++++++----------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index d5adc7dd1a4..03f692e0a97 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -19,6 +19,20 @@ Define the Avro schema for the message payload: You can choose one of the follow
 - Remote reference: Specify the schema using an absolute remote endpoint, such as $ref: 'https://schemas.example.com/user'.
 - Local reference: Specify the schema using a relative reference, such as $ref: './user-signedup.avsc#/User'.
 
+```mermaid
+graph LR
+A[Define Avro Schema]
+B[Local Reference]
+C[Avro Schema File]
+D[Message Payload]
+E[AsyncAPI Specification File]
+
+A -->|One of the following methods:| B
+B -->|Specify schema using relative reference| D
+E -->|Uses local reference method| C
+C-->|Defines structure of message payload| D
+```
+
 Here is an example of an AsyncAPI specification file that uses the local reference method:
 
 ```yaml
@@ -48,20 +62,6 @@ Create a separate Avro schema file with a .avsc extension. The file should defin
 }
 ```
 
-```mermaid
-graph LR
-A[Define Avro Schema]
-B[Local Reference]
-C[Avro Schema File]
-D[Message Payload]
-E[AsyncAPI Specification File]
-
-A -->|One of the following methods:| B
-B -->|Specify schema using relative reference| D
-E -->|Uses local reference method| C
-C-->|Defines structure of message payload| D
-```
-
 ## Attach examples
 
 Although optional, it is highly recommended to attach examples to the AsyncAPI specification. For a binary encoding like Avro, you can use JSON or YAML format. Attach the examples to the examples property within the message payload definition. Here is an example:

From bca219c470fd6e31d0d20a2e896bd7da2a27ca2a Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Fri, 21 Jul 2023 00:14:09 +0530
Subject: [PATCH 04/21] Introduce the image

---
 .../concepts/asyncapi-document/payload-schema.md   | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index 03f692e0a97..b2c3f17b007 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -13,11 +13,13 @@ Use npm or yarn to install the `@asyncapi/avro-schema-parser` package to enable
 
 ## Define Avro schema
 
-Define the Avro schema for the message payload: You can choose one of the following methods:
+Define the Avro schema for the message payload. You can choose one of the following method,
 
 - Embedded notation: Define the Avro schema within the message payload property.
-- Remote reference: Specify the schema using an absolute remote endpoint, such as $ref: 'https://schemas.example.com/user'.
-- Local reference: Specify the schema using a relative reference, such as $ref: './user-signedup.avsc#/User'.
+- Remote reference: Specify the schema using an absolute remote endpoint, such as `$ref: 'https://schemas.example.com/user'`.
+- Local reference: Specify the schema using a relative reference, such as `$ref: './user-signedup.avsc#/User'`.
+
+The diagram below depicts defining AsyncAPI specification file usingg local reference method.
 
 ```mermaid
 graph LR
@@ -33,7 +35,7 @@ E -->|Uses local reference method| C
 C-->|Defines structure of message payload| D
 ```
 
-Here is an example of an AsyncAPI specification file that uses the local reference method:
+Here is an example of an AsyncAPI specification file that uses the local reference method,
 
 ```yaml
 asyncapi: '2.0.0'
@@ -64,7 +66,7 @@ Create a separate Avro schema file with a .avsc extension. The file should defin
 
 ## Attach examples
 
-Although optional, it is highly recommended to attach examples to the AsyncAPI specification. For a binary encoding like Avro, you can use JSON or YAML format. Attach the examples to the examples property within the message payload definition. Here is an example:
+Although optional, it is highly recommended to attach examples to the AsyncAPI specification. For a binary encoding like Avro, you can use JSON or YAML format. Attach the examples to the examples property within the message payload definition. Here is an example,
 
 ```yaml
 asyncapi: '2.0.0'
@@ -82,7 +84,7 @@ You can use a Schema Registry to separate the Avro schema from the message paylo
 
 ## Reuse schema
 
-To reuse a schema in your AsyncAPI specification, define it in the components/schemas section and reference it using the $ref keyword. Using $ref helps to avoid duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI.
+To reuse a schema in your AsyncAPI specification, define it in the components/schemas section and reference it using the `$ref` keyword. Using `$ref` helps to avoid duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI.
 
 ```yaml
 asyncapi: '2.0.0'

From d97f998b712899f23bb99760037f1f4cd169099c Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Sat, 22 Jul 2023 11:46:10 +0530
Subject: [PATCH 05/21] Fix code for version

---
 .../asyncapi-document/payload-schema.md       | 107 ++++++++++--------
 1 file changed, 59 insertions(+), 48 deletions(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index b2c3f17b007..cc8064477f1 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -3,23 +3,23 @@ title: Payload Schema
 weight: 139
 ---
 
-The payload schema defines the format, data types, and properties of a message's payload. To ensure that the payload follows a specific structure and data format.
+The payload schema defines a message's payload's format, data types, and properties. Ensure that the payload follows a specific structure and data format.
 
 In the AsyncAPI specification, you can use schema languages such as JSON or Avro Schema to create the payload schema. Enabling consumers to gain insights into the structure and data types of the payload.
 
-To handle complex messages and structured data models, you should use Avro schemas. Avro schemas support complex types like arrays and records. You can create Avro schemas by writing the JSON representation or by utilising tools like Avro4s UI to generate the schema from valid JSON.
+You should use Avro schemas to handle complex messages and structured data models. Avro schemas support complex types like arrays and records. You can create Avro schemas by writing the JSON representation or using tools like Avro4s UI to generate the schema from valid JSON.
 
 Use npm or yarn to install the `@asyncapi/avro-schema-parser` package to enable Avro schema parsing in AsyncAPI.
 
 ## Define Avro schema
 
-Define the Avro schema for the message payload. You can choose one of the following method,
+Define the Avro schema for the message payload. You can choose one of the following methods,
 
 - Embedded notation: Define the Avro schema within the message payload property.
 - Remote reference: Specify the schema using an absolute remote endpoint, such as `$ref: 'https://schemas.example.com/user'`.
 - Local reference: Specify the schema using a relative reference, such as `$ref: './user-signedup.avsc#/User'`.
 
-The diagram below depicts defining AsyncAPI specification file usingg local reference method.
+The diagram below defines the AsyncAPI specification file using the local reference method.
 
 ```mermaid
 graph LR
@@ -38,46 +38,51 @@ C-->|Defines structure of message payload| D
 Here is an example of an AsyncAPI specification file that uses the local reference method,
 
 ```yaml
-asyncapi: '2.0.0'
-id: 'urn:example.user'
-channels:
-  user/signedup:
-    subscribe:
-      contentType: avro/binary
-      schemaFormat: application/vnd.apache.avro+json;version=1.9.0
-      payload:
-        $ref: './user.avsc#/User'
+{
+  'messageId': 'userSignup',
+  'name': 'UserSignup',
+  'title': 'User signup',
+  'summary': 'Action to sign a user up.',
+  'description': 'A longer description',
+  'tags': [{ 'name': 'user' }, { 'name': 'signup' }],
+  'payload':
+    {
+      'schemaFormat': 'application/vnd.apache.avro+json;version=1.9.0',
+      'schema': { '$ref': 'path/to/user-create.avsc#/UserCreate' },
+    },
+}
 ```
 
 Create a separate Avro schema file with a .avsc extension. The file should define the structure of the message payload. Here is an example of an Avro schema file for the User record type:
 
 ```json
 {
-  "namespace": "example.avro",
+  "namespace": "UserCreate.avro",
   "type": "record",
-  "name": "User",
+  "name": "user",
   "fields": [
     { "name": "fullName", "type": "string" },
-    { "name": "email", "type": "string" },
-    { "name": "age", "type": "int" }
+    { "name": "email", "type": "string" }
   ]
 }
 ```
 
 ## Attach examples
 
-Although optional, it is highly recommended to attach examples to the AsyncAPI specification. For a binary encoding like Avro, you can use JSON or YAML format. Attach the examples to the examples property within the message payload definition. Here is an example,
+Although optional, it is highly recommended to attach examples to the AsyncAPI specification. You can use JSON or YAML format for binary encodings, like Avro. Attach the examples to the examples property within the message payload definition. Here is an example,
 
 ```yaml
-asyncapi: '2.0.0'
-id: 'urn:io.example'
-channels:
-  user/signedup:
-    subscribe:
-      examples:
-        - laurent:
-            payload: |-
-              {"fullName": "Demo", "email": "demo@demo.io", "age": 19}
+{
+  "examples": [
+    {
+      "name": "SimpleSignup",
+      "summary": "A simple UserSignup example message",
+    }
+    "payload":{
+      "user": { 'fullName': 'Demo', 'email': 'demo@demo.io'}
+    }
+  ]
+}
 ```
 
 You can use a Schema Registry to separate the Avro schema from the message payload, making it easier to manage schema compatibility.
@@ -87,25 +92,31 @@ You can use a Schema Registry to separate the Avro schema from the message paylo
 To reuse a schema in your AsyncAPI specification, define it in the components/schemas section and reference it using the `$ref` keyword. Using `$ref` helps to avoid duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI.
 
 ```yaml
-asyncapi: '2.0.0'
-info:
-  title: My AsyncAPI Specification
-  version: '1.0.0'
-channels:
-  user/signedup:
-    subscribe:
-      message:
-        payload:
-          $ref: '#/components/schemas/User'
-components:
-  schemas:
-    User:
-      type: object
-      properties:
-        fullName:
-          type: string
-        email:
-          type: string
-        age:
-          type: integer
+{
+  'channels':
+    {
+      'user/signedup':
+        {
+          'subscribe':
+            {
+              'message': { 'payload': { '$ref': '#/components/schemas/User' } },
+            },
+        },
+    },
+  'components':
+    {
+      'schemas':
+        {
+          'User':
+            {
+              'type': 'object',
+              'properties':
+                {
+                  'fullName': { 'type': 'string' },
+                  'email': { 'type': 'string' },
+                },
+            },
+        },
+    },
+}
 ```

From c3c2e1f965abad6a013ae3836f143b2bbecb80a4 Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Mon, 31 Jul 2023 23:43:21 +0530
Subject: [PATCH 06/21] fix mermaid diagram color

---
 .../asyncapi-document/payload-schema.md       | 76 +++++++++----------
 1 file changed, 37 insertions(+), 39 deletions(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index cc8064477f1..9456b0fb9cd 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -23,6 +23,12 @@ The diagram below defines the AsyncAPI specification file using the local refere
 
 ```mermaid
 graph LR
+style A fill:#47BCEE, stroke:#333, stroke-width:2px;
+style C fill:#47BCEE, stroke:#333, stroke-width:2px;
+style D fill:#47BCEE, stroke:#333, stroke-width:2px;
+style B fill:#47BCEE, stroke:#333, stroke-width:2px;
+style E fill:#47BCEE, stroke:#333, stroke-width:2px;
+
 A[Define Avro Schema]
 B[Local Reference]
 C[Avro Schema File]
@@ -37,19 +43,18 @@ C-->|Defines structure of message payload| D
 
 Here is an example of an AsyncAPI specification file that uses the local reference method,
 
-```yaml
+```json
 {
-  'messageId': 'userSignup',
-  'name': 'UserSignup',
-  'title': 'User signup',
-  'summary': 'Action to sign a user up.',
-  'description': 'A longer description',
-  'tags': [{ 'name': 'user' }, { 'name': 'signup' }],
-  'payload':
-    {
-      'schemaFormat': 'application/vnd.apache.avro+json;version=1.9.0',
-      'schema': { '$ref': 'path/to/user-create.avsc#/UserCreate' },
-    },
+  "messageId": "userSignup",
+  "name": "UserSignup",
+  "title": "User signup",
+  "summary": "Action to sign a user up.",
+  "description": "A longer description",
+  "tags": [{ "name": "user" }, { "name": "signup" }],
+  "payload": {
+    "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
+    "schema": { "$ref": "path/to/user-create.avsc#/UserCreate" }
+  }
 }
 ```
 
@@ -71,7 +76,7 @@ Create a separate Avro schema file with a .avsc extension. The file should defin
 
 Although optional, it is highly recommended to attach examples to the AsyncAPI specification. You can use JSON or YAML format for binary encodings, like Avro. Attach the examples to the examples property within the message payload definition. Here is an example,
 
-```yaml
+```json
 {
   "examples": [
     {
@@ -91,32 +96,25 @@ You can use a Schema Registry to separate the Avro schema from the message paylo
 
 To reuse a schema in your AsyncAPI specification, define it in the components/schemas section and reference it using the `$ref` keyword. Using `$ref` helps to avoid duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI.
 
-```yaml
+```json
 {
-  'channels':
-    {
-      'user/signedup':
-        {
-          'subscribe':
-            {
-              'message': { 'payload': { '$ref': '#/components/schemas/User' } },
-            },
-        },
-    },
-  'components':
-    {
-      'schemas':
-        {
-          'User':
-            {
-              'type': 'object',
-              'properties':
-                {
-                  'fullName': { 'type': 'string' },
-                  'email': { 'type': 'string' },
-                },
-            },
-        },
-    },
+  "channels": {
+    "user/signedup": {
+      "subscribe": {
+        "message": { "payload": { "$ref": "#/components/schemas/User" } }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "User": {
+        "type": "object",
+        "properties": {
+          "fullName": { "type": "string" },
+          "email": { "type": "string" }
+        }
+      }
+    }
+  }
 }
 ```

From d3c183c7661d34aa284cddbe6099456ed7adb034 Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Tue, 29 Aug 2023 19:41:24 +0530
Subject: [PATCH 07/21] Yaml code update

---
 .../asyncapi-document/payload-schema.md       | 106 ++++++++----------
 1 file changed, 48 insertions(+), 58 deletions(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index 9456b0fb9cd..1c08b5ecfeb 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -1,9 +1,9 @@
 ---
 title: Payload Schema
-weight: 139
+weight: 239
 ---
 
-The payload schema defines a message's payload's format, data types, and properties. Ensure that the payload follows a specific structure and data format.
+The payload schema defines a message's format, data types, and properties to ensure that the payload follows a specific structure and data format.
 
 In the AsyncAPI specification, you can use schema languages such as JSON or Avro Schema to create the payload schema. Enabling consumers to gain insights into the structure and data types of the payload.
 
@@ -43,51 +43,46 @@ C-->|Defines structure of message payload| D
 
 Here is an example of an AsyncAPI specification file that uses the local reference method,
 
-```json
-{
-  "messageId": "userSignup",
-  "name": "UserSignup",
-  "title": "User signup",
-  "summary": "Action to sign a user up.",
-  "description": "A longer description",
-  "tags": [{ "name": "user" }, { "name": "signup" }],
-  "payload": {
-    "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
-    "schema": { "$ref": "path/to/user-create.avsc#/UserCreate" }
-  }
-}
+```yaml
+messageId: userSignup
+name: UserSignup
+title: User signup
+summary: Action to sign a user up.
+description: A longer description
+tags:
+  - name: user
+  - name: signup
+payload:
+  schemaFormat: application/vnd.apache.avro+json;version=1.9.0
+  schema:
+    $ref: path/to/user-create.avsc#/UserCreate
 ```
 
 Create a separate Avro schema file with a .avsc extension. The file should define the structure of the message payload. Here is an example of an Avro schema file for the User record type:
 
-```json
-{
-  "namespace": "UserCreate.avro",
-  "type": "record",
-  "name": "user",
-  "fields": [
-    { "name": "fullName", "type": "string" },
-    { "name": "email", "type": "string" }
-  ]
-}
+```yaml
+namespace: UserCreate.avro
+type: record
+name: user
+fields:
+  - name: fullName
+    type: string
+  - name: email
+    type: string
 ```
 
 ## Attach examples
 
 Although optional, it is highly recommended to attach examples to the AsyncAPI specification. You can use JSON or YAML format for binary encodings, like Avro. Attach the examples to the examples property within the message payload definition. Here is an example,
 
-```json
-{
-  "examples": [
-    {
-      "name": "SimpleSignup",
-      "summary": "A simple UserSignup example message",
-    }
-    "payload":{
-      "user": { 'fullName': 'Demo', 'email': 'demo@demo.io'}
-    }
-  ]
-}
+```yaml
+examples:
+  - name: SimpleSignup
+    summary: A simple UserSignup example message
+  - payload:
+      user:
+        fullName: Demo
+        email: demo@demo.io
 ```
 
 You can use a Schema Registry to separate the Avro schema from the message payload, making it easier to manage schema compatibility.
@@ -96,25 +91,20 @@ You can use a Schema Registry to separate the Avro schema from the message paylo
 
 To reuse a schema in your AsyncAPI specification, define it in the components/schemas section and reference it using the `$ref` keyword. Using `$ref` helps to avoid duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI.
 
-```json
-{
-  "channels": {
-    "user/signedup": {
-      "subscribe": {
-        "message": { "payload": { "$ref": "#/components/schemas/User" } }
-      }
-    }
-  },
-  "components": {
-    "schemas": {
-      "User": {
-        "type": "object",
-        "properties": {
-          "fullName": { "type": "string" },
-          "email": { "type": "string" }
-        }
-      }
-    }
-  }
-}
+```yaml
+channels:
+  user/signedup:
+    subscribe:
+      message:
+        payload:
+          $ref: '#/components/schemas/User'
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        fullName:
+          type: string
+        email:
+          type: string
 ```

From 900be20a8241be301faa51f8d18ef539e14a11bc Mon Sep 17 00:00:00 2001
From: hridyesh bisht <41201308+kakabisht@users.noreply.github.com>
Date: Mon, 4 Sep 2023 14:39:07 +0530
Subject: [PATCH 08/21] Update
 pages/docs/concepts/asyncapi-document/payload-schema.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fran Méndez <fmvilas@gmail.com>
---
 pages/docs/concepts/asyncapi-document/payload-schema.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index 1c08b5ecfeb..f689bcce158 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -5,7 +5,7 @@ weight: 239
 
 The payload schema defines a message's format, data types, and properties to ensure that the payload follows a specific structure and data format.
 
-In the AsyncAPI specification, you can use schema languages such as JSON or Avro Schema to create the payload schema. Enabling consumers to gain insights into the structure and data types of the payload.
+In the AsyncAPI specification, you can use schema languages such as JSON Schema or Avro to create the payload schema. Enabling consumers to gain insights into the structure and data types of the payload.
 
 You should use Avro schemas to handle complex messages and structured data models. Avro schemas support complex types like arrays and records. You can create Avro schemas by writing the JSON representation or using tools like Avro4s UI to generate the schema from valid JSON.
 

From bd03c289216f619cc0ec98573e962ab2b5f6c983 Mon Sep 17 00:00:00 2001
From: hridyesh bisht <41201308+kakabisht@users.noreply.github.com>
Date: Mon, 4 Sep 2023 14:40:41 +0530
Subject: [PATCH 09/21] Update
 pages/docs/concepts/asyncapi-document/payload-schema.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fran Méndez <fmvilas@gmail.com>
---
 pages/docs/concepts/asyncapi-document/payload-schema.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index f689bcce158..45feb27bc01 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -17,7 +17,7 @@ Define the Avro schema for the message payload. You can choose one of the follow
 
 - Embedded notation: Define the Avro schema within the message payload property.
 - Remote reference: Specify the schema using an absolute remote endpoint, such as `$ref: 'https://schemas.example.com/user'`.
-- Local reference: Specify the schema using a relative reference, such as `$ref: './user-signedup.avsc#/User'`.
+- Local file reference: Specify the schema using a relative reference, such as `$ref: './user-signedup.avsc'`.
 
 The diagram below defines the AsyncAPI specification file using the local reference method.
 

From 47f7c501753219de03c5c4266e91c4f802f21556 Mon Sep 17 00:00:00 2001
From: hridyesh bisht <41201308+kakabisht@users.noreply.github.com>
Date: Mon, 4 Sep 2023 14:42:53 +0530
Subject: [PATCH 10/21] Update
 pages/docs/concepts/asyncapi-document/payload-schema.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fran Méndez <fmvilas@gmail.com>
---
 pages/docs/concepts/asyncapi-document/payload-schema.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index 45feb27bc01..abb2b4b0ba8 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -13,7 +13,7 @@ Use npm or yarn to install the `@asyncapi/avro-schema-parser` package to enable
 
 ## Define Avro schema
 
-Define the Avro schema for the message payload. You can choose one of the following methods,
+Define the Avro schema for the message payload. You can choose one of the following methods:
 
 - Embedded notation: Define the Avro schema within the message payload property.
 - Remote reference: Specify the schema using an absolute remote endpoint, such as `$ref: 'https://schemas.example.com/user'`.

From 167644ca8b61b1362ca837d965f02ffd9bc4cd70 Mon Sep 17 00:00:00 2001
From: hridyesh bisht <41201308+kakabisht@users.noreply.github.com>
Date: Mon, 4 Sep 2023 14:43:19 +0530
Subject: [PATCH 11/21] Update
 pages/docs/concepts/asyncapi-document/payload-schema.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fran Méndez <fmvilas@gmail.com>
---
 pages/docs/concepts/asyncapi-document/payload-schema.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index abb2b4b0ba8..aac40012d8d 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -41,7 +41,7 @@ E -->|Uses local reference method| C
 C-->|Defines structure of message payload| D
 ```
 
-Here is an example of an AsyncAPI specification file that uses the local reference method,
+Here is an example of an AsyncAPI specification file that uses the local reference method:
 
 ```yaml
 messageId: userSignup

From 583c51b3cdb9a1b225315359c4a7dede08c79926 Mon Sep 17 00:00:00 2001
From: hridyesh bisht <41201308+kakabisht@users.noreply.github.com>
Date: Mon, 4 Sep 2023 14:43:57 +0530
Subject: [PATCH 12/21] Update
 pages/docs/concepts/asyncapi-document/payload-schema.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fran Méndez <fmvilas@gmail.com>
---
 pages/docs/concepts/asyncapi-document/payload-schema.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index aac40012d8d..b5ca5f5ca3b 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -55,7 +55,7 @@ tags:
 payload:
   schemaFormat: application/vnd.apache.avro+json;version=1.9.0
   schema:
-    $ref: path/to/user-create.avsc#/UserCreate
+    $ref: path/to/user-create.avsc
 ```
 
 Create a separate Avro schema file with a .avsc extension. The file should define the structure of the message payload. Here is an example of an Avro schema file for the User record type:

From 42fbf4d2d11a76c7c25e2a7aa233df3b864eed62 Mon Sep 17 00:00:00 2001
From: hridyesh bisht <41201308+kakabisht@users.noreply.github.com>
Date: Mon, 4 Sep 2023 14:44:40 +0530
Subject: [PATCH 13/21] Update
 pages/docs/concepts/asyncapi-document/_section.md

Co-authored-by: Alejandra Quetzalli  <alejandra.quetzalli@postman.com>
---
 pages/docs/concepts/asyncapi-document/_section.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md
index 9ee6204f423..fc223bd8a9d 100644
--- a/pages/docs/concepts/asyncapi-document/_section.md
+++ b/pages/docs/concepts/asyncapi-document/_section.md
@@ -1,4 +1,4 @@
 ---
-title: AsyncAPI-document
+title: AsyncAPI document
 weight: 0
 ---

From 7a6b76df6cab9b085755791f456cc7da9ef423b9 Mon Sep 17 00:00:00 2001
From: hridyesh bisht <41201308+kakabisht@users.noreply.github.com>
Date: Mon, 4 Sep 2023 14:44:56 +0530
Subject: [PATCH 14/21] Update
 pages/docs/concepts/asyncapi-document/payload-schema.md

Co-authored-by: Alejandra Quetzalli  <alejandra.quetzalli@postman.com>
---
 pages/docs/concepts/asyncapi-document/payload-schema.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index b5ca5f5ca3b..ca34d894454 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -58,7 +58,7 @@ payload:
     $ref: path/to/user-create.avsc
 ```
 
-Create a separate Avro schema file with a .avsc extension. The file should define the structure of the message payload. Here is an example of an Avro schema file for the User record type:
+Create a separate Avro schema file with a `.avsc` extension. The file should define the structure of the message payload. Here is an example of an Avro schema file for the user record type:
 
 ```yaml
 namespace: UserCreate.avro

From 893d3c030922285e3cf227120b35eb29d50c0334 Mon Sep 17 00:00:00 2001
From: hridyesh bisht <41201308+kakabisht@users.noreply.github.com>
Date: Mon, 4 Sep 2023 14:46:52 +0530
Subject: [PATCH 15/21] Update
 pages/docs/concepts/asyncapi-document/payload-schema.md

Co-authored-by: Alejandra Quetzalli  <alejandra.quetzalli@postman.com>
---
 pages/docs/concepts/asyncapi-document/payload-schema.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index ca34d894454..c5317e3877e 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -89,7 +89,7 @@ You can use a Schema Registry to separate the Avro schema from the message paylo
 
 ## Reuse schema
 
-To reuse a schema in your AsyncAPI specification, define it in the components/schemas section and reference it using the `$ref` keyword. Using `$ref` helps to avoid duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI.
+To reuse a schema in your AsyncAPI specification, define it in the `components/schemas` section and reference it using the `$ref` keyword. Using `$ref` helps to avoid duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI.
 
 ```yaml
 channels:

From a4ed37dc14e5c2da7e9c24ad368fe395a711fb48 Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Mon, 4 Sep 2023 15:39:40 +0530
Subject: [PATCH 16/21] partial SME feedback

---
 .../asyncapi-document/payload-schema.md       | 27 ++++++++++++-------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index 1c08b5ecfeb..87ed43dce94 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -7,7 +7,7 @@ The payload schema defines a message's format, data types, and properties to ens
 
 In the AsyncAPI specification, you can use schema languages such as JSON or Avro Schema to create the payload schema. Enabling consumers to gain insights into the structure and data types of the payload.
 
-You should use Avro schemas to handle complex messages and structured data models. Avro schemas support complex types like arrays and records. You can create Avro schemas by writing the JSON representation or using tools like Avro4s UI to generate the schema from valid JSON.
+You should use Avro schemas to handle complex messages and structured data models. Avro schemas support complex types like arrays and records. You can create Avro schemas by writing the JSON representation.
 
 Use npm or yarn to install the `@asyncapi/avro-schema-parser` package to enable Avro schema parsing in AsyncAPI.
 
@@ -60,15 +60,22 @@ payload:
 
 Create a separate Avro schema file with a .avsc extension. The file should define the structure of the message payload. Here is an example of an Avro schema file for the User record type:
 
-```yaml
-namespace: UserCreate.avro
-type: record
-name: user
-fields:
-  - name: fullName
-    type: string
-  - name: email
-    type: string
+```json
+{
+  "namespace": "UserCreate.avro",
+  "type": "record",
+  "name": "user",
+  "fields": [
+    {
+      "name": "fullName",
+      "type": "string"
+    },
+    {
+      "name": "email",
+      "type": "string"
+    }
+  ]
+}
 ```
 
 ## Attach examples

From c499ac7fbac5d3ffb9b4844a1cbce138043832ae Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Thu, 14 Sep 2023 14:14:49 +0530
Subject: [PATCH 17/21] fix weights

---
 pages/docs/concepts/asyncapi-document/_section.md       | 2 +-
 pages/docs/concepts/asyncapi-document/payload-schema.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md
index fc223bd8a9d..6848f98cbcf 100644
--- a/pages/docs/concepts/asyncapi-document/_section.md
+++ b/pages/docs/concepts/asyncapi-document/_section.md
@@ -1,4 +1,4 @@
 ---
 title: AsyncAPI document
-weight: 0
+weight: 50
 ---
diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index 404aa965a2f..c46756e0999 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -1,6 +1,6 @@
 ---
 title: Payload Schema
-weight: 239
+weight: 270
 ---
 
 The payload schema defines a message's format, data types, and properties to ensure that the payload follows a specific structure and data format.

From 4b55f6a38f8c34872a4f516249d2b77771704a55 Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Fri, 15 Sep 2023 15:01:17 +0530
Subject: [PATCH 18/21] Partial SME feedback

---
 pages/docs/concepts/asyncapi-document/payload-schema.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi-document/payload-schema.md
index c46756e0999..292e4d966db 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi-document/payload-schema.md
@@ -5,9 +5,7 @@ weight: 270
 
 The payload schema defines a message's format, data types, and properties to ensure that the payload follows a specific structure and data format.
 
-In the AsyncAPI specification, you can use schema languages such as JSON Schema or Avro to create the payload schema. Enabling consumers to gain insights into the structure and data types of the payload.
-
-You should use Avro schemas to handle complex messages and structured data models. Avro schemas support complex types like arrays and records. You can create Avro schemas by writing the JSON representation.
+You should use AsyncAPI Schema to handle complex messages and structured data models. Enabling consumers to gain insights into the structure and data types of the payload.
 
 Use npm or yarn to install the `@asyncapi/avro-schema-parser` package to enable Avro schema parsing in AsyncAPI.
 

From 668a36d35e61ca391bdd7ae0f7896c1384d678d7 Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Tue, 10 Oct 2023 19:42:21 +0530
Subject: [PATCH 19/21] Complete SME feedback

---
 .../{asyncapi-document => asyncapi document}/_section.md  | 0
 .../payload-schema.md                                     | 8 ++++----
 2 files changed, 4 insertions(+), 4 deletions(-)
 rename pages/docs/concepts/{asyncapi-document => asyncapi document}/_section.md (100%)
 rename pages/docs/concepts/{asyncapi-document => asyncapi document}/payload-schema.md (95%)

diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi document/_section.md
similarity index 100%
rename from pages/docs/concepts/asyncapi-document/_section.md
rename to pages/docs/concepts/asyncapi document/_section.md
diff --git a/pages/docs/concepts/asyncapi-document/payload-schema.md b/pages/docs/concepts/asyncapi document/payload-schema.md
similarity index 95%
rename from pages/docs/concepts/asyncapi-document/payload-schema.md
rename to pages/docs/concepts/asyncapi document/payload-schema.md
index 292e4d966db..49110bf65dd 100644
--- a/pages/docs/concepts/asyncapi-document/payload-schema.md
+++ b/pages/docs/concepts/asyncapi document/payload-schema.md	
@@ -33,10 +33,10 @@ C[Avro Schema File]
 D[Message Payload]
 E[AsyncAPI Specification File]
 
-A -->|One of the following methods:| B
-B -->|Specify schema using relative reference| D
-E -->|Uses local reference method| C
-C-->|Defines structure of message payload| D
+A -->|Specifies| B
+B -->|Specifies schema| D
+E -->|Uses| C
+C -->|Defines structure| D
 ```
 
 Here is an example of an AsyncAPI specification file that uses the local reference method:

From fa9eb791fe1a8f4d3b19fb92ebbbe3d8436d696a Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Thu, 16 Nov 2023 12:50:10 +0530
Subject: [PATCH 20/21] fixing the image

---
 .../asyncapi document/payload-schema.md       | 32 ++++++++-----------
 1 file changed, 14 insertions(+), 18 deletions(-)

diff --git a/pages/docs/concepts/asyncapi document/payload-schema.md b/pages/docs/concepts/asyncapi document/payload-schema.md
index 49110bf65dd..2544c08b441 100644
--- a/pages/docs/concepts/asyncapi document/payload-schema.md	
+++ b/pages/docs/concepts/asyncapi document/payload-schema.md	
@@ -17,26 +17,22 @@ Define the Avro schema for the message payload. You can choose one of the follow
 - Remote reference: Specify the schema using an absolute remote endpoint, such as `$ref: 'https://schemas.example.com/user'`.
 - Local file reference: Specify the schema using a relative reference, such as `$ref: './user-signedup.avsc'`.
 
-The diagram below defines the AsyncAPI specification file using the local reference method.
+The diagram below describes how to use complex payloads.
 
 ```mermaid
-graph LR
-style A fill:#47BCEE, stroke:#333, stroke-width:2px;
-style C fill:#47BCEE, stroke:#333, stroke-width:2px;
-style D fill:#47BCEE, stroke:#333, stroke-width:2px;
-style B fill:#47BCEE, stroke:#333, stroke-width:2px;
-style E fill:#47BCEE, stroke:#333, stroke-width:2px;
-
-A[Define Avro Schema]
-B[Local Reference]
-C[Avro Schema File]
-D[Message Payload]
-E[AsyncAPI Specification File]
-
-A -->|Specifies| B
-B -->|Specifies schema| D
-E -->|Uses| C
-C -->|Defines structure| D
+graph TD
+    A[Message]
+    B[Payload]
+    C[Avro Schema]
+
+style A fill:#47BCEE,stroke:#47BCEE;
+style B fill:#47BCEE,stroke:#47BCEE;
+style C fill:#47BCEE,stroke:#47BCEE;
+
+  A -->|references| B
+  B -->|local file reference| C
+  B -->|remote reference| C
+  B -->|embedded notation| C
 ```
 
 Here is an example of an AsyncAPI specification file that uses the local reference method:

From c337d2adda3936d08cd2ae32a046e35b698217a0 Mon Sep 17 00:00:00 2001
From: kakabisht <kakabisht07@gmail.com>
Date: Sat, 2 Dec 2023 14:56:12 +0530
Subject: [PATCH 21/21] Fix for JSON Schema

---
 .../asyncapi document/payload-schema.md       | 97 ++++++++++---------
 1 file changed, 52 insertions(+), 45 deletions(-)

diff --git a/pages/docs/concepts/asyncapi document/payload-schema.md b/pages/docs/concepts/asyncapi document/payload-schema.md
index 2544c08b441..e1f5e10f99e 100644
--- a/pages/docs/concepts/asyncapi document/payload-schema.md	
+++ b/pages/docs/concepts/asyncapi document/payload-schema.md	
@@ -7,15 +7,13 @@ The payload schema defines a message's format, data types, and properties to ens
 
 You should use AsyncAPI Schema to handle complex messages and structured data models. Enabling consumers to gain insights into the structure and data types of the payload.
 
-Use npm or yarn to install the `@asyncapi/avro-schema-parser` package to enable Avro schema parsing in AsyncAPI.
+## Define JSON schema
 
-## Define Avro schema
+Define the JSON schema for the message payload. You can choose one of the following methods:
 
-Define the Avro schema for the message payload. You can choose one of the following methods:
-
-- Embedded notation: Define the Avro schema within the message payload property.
+- Inline reference: Define the JSON schema within the message payload property.
 - Remote reference: Specify the schema using an absolute remote endpoint, such as `$ref: 'https://schemas.example.com/user'`.
-- Local file reference: Specify the schema using a relative reference, such as `$ref: './user-signedup.avsc'`.
+- Local file reference: Specify the schema using a relative reference, such as `$ref: './user-signedup.json'`.
 
 The diagram below describes how to use complex payloads.
 
@@ -23,7 +21,7 @@ The diagram below describes how to use complex payloads.
 graph TD
     A[Message]
     B[Payload]
-    C[Avro Schema]
+    C[JSON Schema]
 
 style A fill:#47BCEE,stroke:#47BCEE;
 style B fill:#47BCEE,stroke:#47BCEE;
@@ -32,49 +30,54 @@ style C fill:#47BCEE,stroke:#47BCEE;
   A -->|references| B
   B -->|local file reference| C
   B -->|remote reference| C
-  B -->|embedded notation| C
+  B -->|Inline reference| C
 ```
 
 Here is an example of an AsyncAPI specification file that uses the local reference method:
 
 ```yaml
-messageId: userSignup
-name: UserSignup
-title: User signup
-summary: Action to sign a user up.
-description: A longer description
-tags:
-  - name: user
-  - name: signup
-payload:
-  schemaFormat: application/vnd.apache.avro+json;version=1.9.0
-  schema:
-    $ref: path/to/user-create.avsc
+channels:
+  exampleChannel:
+    address: exampleChannel
+    messages:
+      publish.message:
+        payload:
+          $ref: path/to/user-create.json
+operations:
+  exampleChannel.publish:
+    action: receive
+    channel:
+      $ref: '#/channels/exampleChannel'
+    messages:
+      - $ref: '#/channels/exampleChannel/messages/publish.message'
 ```
 
-Create a separate Avro schema file with a `.avsc` extension. The file should define the structure of the message payload. Here is an example of an Avro schema file for the user record type:
+Create a separate JSON schema file with a `.json` extension. The file should define the structure of the message payload. Here is an example of a JSON schema file for the user record type:
 
 ```json
 {
-  "namespace": "UserCreate.avro",
-  "type": "record",
-  "name": "user",
-  "fields": [
-    {
-      "name": "fullName",
-      "type": "string"
+  "type": "object",
+  "properties": {
+    "username": {
+      "type": "string",
+      "description": "The username of the sender"
+    },
+    "email": {
+      "type": "string",
+      "format": "email",
+      "description": "The email of the sender"
     },
-    {
-      "name": "email",
-      "type": "string"
+    "message": {
+      "type": "string",
+      "description": "The content of the message"
     }
-  ]
+  }
 }
 ```
 
 ## Attach examples
 
-Although optional, it is highly recommended to attach examples to the AsyncAPI specification. You can use JSON or YAML format for binary encodings, like Avro. Attach the examples to the examples property within the message payload definition. Here is an example,
+Although optional, it is highly recommended to attach examples to the AsyncAPI specification. You can use JSON or YAML format for binary encodings. Attach the examples to the examples property within the message payload definition. Here is an example,
 
 ```yaml
 examples:
@@ -82,29 +85,33 @@ examples:
     summary: A simple UserSignup example message
   - payload:
       user:
-        fullName: Demo
+        name: Demo
         email: demo@demo.io
 ```
 
-You can use a Schema Registry to separate the Avro schema from the message payload, making it easier to manage schema compatibility.
-
 ## Reuse schema
 
 To reuse a schema in your AsyncAPI specification, define it in the `components/schemas` section and reference it using the `$ref` keyword. Using `$ref` helps to avoid duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI.
 
 ```yaml
-channels:
-  user/signedup:
-    subscribe:
-      message:
-        payload:
-          $ref: '#/components/schemas/User'
 components:
-  schemas:
-    User:
+  messages:
+    SimpleSignup:
+      name: SimpleSignup
+      contentType: application/json
+      payload:
+        $ref: '#/components/schemas/SimpleSignup'
+    examples:
+      name: example
+      payload: 
+        SimpleSignup:
+          name: Demo
+          email: demo@demo.io
+schemas:
+    SimpleSignup:
       type: object
       properties:
-        fullName:
+        name:
           type: string
         email:
           type: string