Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: new traits merge mechanism #907

Merged
merged 9 commits into from
Jul 13, 2023
Merged

feat: new traits merge mechanism #907

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
fdc93d3
feat: new traits merge mechanism
magicmatatjahu Feb 16, 2023
53ede05
Apply suggestions from code review
magicmatatjahu Apr 2, 2023
2121454
switched to target
jonaslagoni Jun 13, 2023
36e816d
Merge branch 'next-major-spec' into next-major/new-trait-bechaviour
jonaslagoni Jun 13, 2023
e2d3f73
add missing endtag on codeblock
jonaslagoni Jun 13, 2023
51ed5db
Update spec/asyncapi.md
jonaslagoni Jun 13, 2023
5b17dca
Merge branch 'next-major-spec' into next-major/new-trait-bechaviour
jonaslagoni Jun 20, 2023
5a2ee1e
Update spec/asyncapi.md
jonaslagoni Jun 20, 2023
e38d925
Merge branch 'next-major-spec' into next-major/new-trait-bechaviour
smoya Jun 30, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 28 additions & 2 deletions spec/asyncapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -838,7 +838,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).
<a name="operationObjectMessages"></a>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.
<a name="operationObjectReply"></a>reply | [Operation Reply Object](#operationReplyObject) &#124; [Reference Object](#referenceObject) | The definition of the reply in a request-reply operation.

Expand Down Expand Up @@ -1240,7 +1240,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).

Expand Down Expand Up @@ -2625,6 +2625,32 @@ 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 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.
Copy link

@Fannon Fannon Jun 21, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When implementing this, I think we need to be a bit careful here. The JSON Merge Patch is meant to overwrite the target by design. It's not just making sure that properties are not overridden, also the "null" semantics of JSON Merge Patch is then not applicable, I think.

But I like that this solution is very concise and you avoided defining your own merge algorithm.

Imho, it would be very nice to point to a reference implementation or code snippet how this is to be implemented correctly. As a Dev, I would feel more confident looking at a code example to check my understanding. I like the example, but a simple example cannot cover all the interesting corner cases :)

Copy link
Member

@smoya smoya Jun 30, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I created a followup issue for your suggestion @Fannon asyncapi/website#1879

cc @jonaslagoni @magicmatatjahu @derberg


#### Example

An object like the following:

```yaml
description: A longer description.
traits:
- name: UserSignup
description: Description from trait.
- tags:
fmvilas marked this conversation as resolved.
Show resolved Hide resolved
- name: user
```

Would look like the following after applying traits:

```yaml
name: UserSignup
description: A longer description.
tags:
- name: user
```

### <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.
Expand Down
Loading