From 2ff014b9ebb6f3da082936d009b4f48c623dee1c Mon Sep 17 00:00:00 2001
From: Matatjahu <urbanczyk.maciej.95@gmail.com>
Date: Thu, 16 Feb 2023 11:49:18 +0100
Subject: [PATCH] feat: new traits merge mechanism

---
 spec/asyncapi.md | 42 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/spec/asyncapi.md b/spec/asyncapi.md
index 4454d3364..713ae9fc1 100644
--- a/spec/asyncapi.md
+++ b/spec/asyncapi.md
@@ -835,7 +835,7 @@ Field Name | Type | Description
 <a name="operationObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations.
 <a name="operationObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation.
 <a name="operationObjectBindings"></a>bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.
-<a name="operationObjectTraits"></a>traits | [[Operation Trait Object](#operationTraitObject) &#124; [Reference Object](#referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here.
+<a name="operationObjectTraits"></a>traits | [[Operation Trait Object](#operationTraitObject) &#124; [Reference Object](#referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged using [traits merge mechanism](#traits-merge-mechanism). The resulting object MUST be a valid [Operation Object](#operationObject).
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -1194,7 +1194,7 @@ Field Name | Type | Description
 <a name="messageObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this message.
 <a name="messageObjectBindings"></a>bindings | [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject) | 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 | [[Message Example Object](#messageExampleObject)] | List of examples.
-<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).
+<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 using [traits merge mechanism](#traits-merge-mechanism). The resulting object MUST be a valid [Message Object](#messageObject).
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -2553,6 +2553,44 @@ Message Payload Property | `$message.payload#/messageId` | Correlation ID is set
 
 Runtime expressions preserve the type of the referenced value.
 
+### <a name="traitsMergeMechanism"></a>Traits merge mechanism
+
+Traits MUST be merged into the corresponding object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined with the priority of fields defined on the main object.
+
+The object like (based on [Message Object](#message-object)):
+
+```yaml
+messageId: userSignup
+description: A longer description.
+payload:
+  $ref: '#/components/schemas/userSignupPayload'
+traits:
+  - name: UserSignup
+    title: User signup
+    summary: Action to sign a user up.
+    description: Description from trait.
+  - tags:
+      - name: user
+      - name: signup
+      - name: register
+```
+
+after trait merging should be defined as:
+
+```yaml
+messageId: userSignup
+name: UserSignup
+title: User signup
+summary: Action to sign a user up.
+description: A longer description.
+payload:
+  $ref: '#/components/schemas/userSignupPayload'
+tags:
+  - name: user
+  - name: signup
+  - name: register
+```
+
 ### <a name="specificationExtensions"></a>Specification Extensions
 
 While the AsyncAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.