fix: clarify that traits overwrite the objects they are applied to #517
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.
Fannon
changed the title
Fannon
changed the title
|
Kudos, SonarCloud Quality Gate passed!
|
| @@ -657,7 +657,7 @@ Field Name | Type | Description | |||
| <a name="operationObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. | |||
| <a name="operationObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | 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) | [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) | [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. The resulting object MUST be a valid [Operation Object](#operationObject). **WARNING**: Please be aware that due to the defined order of merge patching, a trait will actually *overwrite* the properties of the object they are applied to. | |||
There was a problem hiding this comment.
This description might get a bit too long and is partially duplicated with the Message Trait Object description.
One option would be to introduce a dedicated section in the spec where both can point to. This section could then also carry more information and explain the traits in more detail.
There was a problem hiding this comment.
I wonder if it would make sense to clarify what #505 estates: as the JSON Merge Patch mentions, arrays are fully replaced as a whole value (by the ones in the trait).
There was a problem hiding this comment.
Yes, this should also be clarified probably.
If we need further clarification, having a dedicated section where we can refer to would make all the more sense.
Btw. I've created an alternative PR which has such a section, but also redefines the behavior: #532
|
This pull request has been automatically marked as stale because it has not had recent activity 😴 |
Description
This PR will add some clarification (basically a warning) that a traits properties will overwrite the properties of the object it is applied to. This is potentially counter-intuitive. For more explanations, please see #505 and this comment: #505 (comment)
Related issue(s)
See also #505