From fdc93d3f7da4c5b474dd5c90f6a62a6fd43e9a6a Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Thu, 16 Feb 2023 11:49:18 +0100 Subject: [PATCH 1/6] 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 d3e603846..4c3991219 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -837,7 +837,7 @@ Field Name | Type | Description tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation. 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. -traits | [[Operation Trait Object](#operationTraitObject) | [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. +traits | [[Operation Trait Object](#operationTraitObject) | [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). messages | [[Reference Object](#referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#messageObject) that can be processed by this operation. It MUST contain a subset of the messages defined in the [channel referenced in this operation](#operationObjectChannel). **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#messageObject) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain [Message Objects](#messageObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. reply | [Operation Reply Object](#operationReplyObject) | [Reference Object](#referenceObject) | The definition of the reply in a request-reply operation. @@ -1266,7 +1266,7 @@ Field Name | Type | Description externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this message. 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. examples | [[Message Example Object](#messageExampleObject)] | List of examples. -traits | [[Message Trait Object](#messageTraitObject) | [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). +traits | [[Message Trait Object](#messageTraitObject) | [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). @@ -2627,6 +2627,44 @@ Message Payload Property | `$message.payload#/messageId` | Correlation ID is set Runtime expressions preserve the type of the referenced value. +### 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 +``` + ### Specification Extensions While the AsyncAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. From 53ede05f79c177f226bb38f4a9c611defaab38da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Urba=C5=84czyk?= Date: Sun, 2 Apr 2023 14:27:29 +0200 Subject: [PATCH 2/6] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fran Méndez --- spec/asyncapi.md | 25 ++++++------------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 4c3991219..a2fe191dc 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -2627,43 +2627,30 @@ Message Payload Property | `$message.payload#/messageId` | Correlation ID is set Runtime expressions preserve the type of the referenced value. -### Traits merge mechanism +### 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. +Traits MUST be merged with the main object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the main object. -The object like (based on [Message Object](#message-object)): +#### Example + +An object like the following: ```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: +Would look like the following after applying traits: ```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 -``` ### Specification Extensions From 2121454897773f987dc5729c0df3f80376ceb126 Mon Sep 17 00:00:00 2001 From: "jonas-lt@live.dk" Date: Tue, 13 Jun 2023 14:04:10 +0200 Subject: [PATCH 3/6] switched to target --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index a2fe191dc..f59914405 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -2629,7 +2629,7 @@ Runtime expressions preserve the type of the referenced value. ### Traits Merge Mechanism -Traits MUST be merged with the main object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the main object. +Traits MUST be merged with the target using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the main object. #### Example From e2d3f7304db0d05d3d248c2656c27695f8c8f3fd Mon Sep 17 00:00:00 2001 From: "jonas-lt@live.dk" Date: Tue, 13 Jun 2023 14:06:48 +0200 Subject: [PATCH 4/6] add missing endtag on codeblock --- spec/asyncapi.md | 1 + 1 file changed, 1 insertion(+) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 6d5271640..b9c087986 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -2650,6 +2650,7 @@ name: UserSignup description: A longer description. tags: - name: user +``` ### Specification Extensions From 51ed5db48bac1356be81a1ff5535f90a215a992e Mon Sep 17 00:00:00 2001 From: Jonas Lagoni Date: Tue, 13 Jun 2023 18:27:05 +0200 Subject: [PATCH 5/6] Update spec/asyncapi.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fran Méndez --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index b9c087986..9e8a8d8a5 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -2628,7 +2628,7 @@ Runtime expressions preserve the type of the referenced value. ### Traits Merge Mechanism -Traits MUST be merged with the target using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the main object. +Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the main object. #### Example From 5a2ee1e96ee382a191649f2a2b424bc39dac691c Mon Sep 17 00:00:00 2001 From: Jonas Lagoni Date: Tue, 20 Jun 2023 15:51:47 +0200 Subject: [PATCH 6/6] Update spec/asyncapi.md --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 3be83e6ad..165f1376e 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -2627,7 +2627,7 @@ Runtime expressions preserve the type of the referenced value. ### Traits Merge Mechanism -Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the main object. +Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the target object. #### Example