From fdc93d3f7da4c5b474dd5c90f6a62a6fd43e9a6a Mon Sep 17 00:00:00 2001 From: Matatjahu 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 d3e60384..4c399121 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.