diff --git a/spec/asyncapi.md b/spec/asyncapi.md index ea5c31567..efde0ab8b 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -87,6 +87,7 @@ Aside from the issues mentioned above, there may also be infrastructure configur - [Default Content Type](#defaultContentTypeString) - [Channels Object](#channelsObject) - [Channel Object](#channelObject) + - [Channel Trait Object](#channelTraitObject) - [Operations Object](#operationsObject) - [Operation Object](#operationObject) - [Operation Trait Object](#operationTraitObject) @@ -652,6 +653,7 @@ Field Name | Type | Description tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this channel. bindings | [Channel Bindings Object](#channelBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. +traits | [[Channel Trait Object](#channelTraitObject) | [Reference Object](#referenceObject)] | A list of traits to apply to the channel object. Traits MUST be merged using [traits merge mechanism](#traits-merge-mechanism). The resulting object MUST be a valid [Channel Object](#channelObject). This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -695,7 +697,10 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "externalDocs": { "description": "Find more info here", "url": "https://example.com" - } + }, + "traits": [ + { "$ref": "#/components/channelTraits/kafkaTopicsCommon" } + ] } ``` @@ -726,6 +731,60 @@ tags: externalDocs: description: 'Find more info here' url: 'https://example.com' +traits: + - $ref: '#/components/channelTraits/kafkaTopicsCommon' +``` + +#### Channel Trait Object + +Describes a trait that MAY be applied to a [Channel Object](#channelObject). This object MAY contain any property from the [Channel Object](#channelObject), except the `address`, `messages` and `traits` ones. + +If you're looking to apply traits to an operation, see the [Operation Trait Object](#operationTraitObject). +If you're looking to apply traits to a message, see the [Message Trait Object](#messageTraitObject). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +title | `string` | A human-friendly title for the channel. +summary | `string` | A short summary of the channel. +description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +servers | [[Reference Object](#referenceObject)] | An array of `$ref` pointers to the definition of the servers in which this channel is available. +parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this channel. +bindings | [Channel Bindings Object](#channelBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Channel Trait Object Example + + +```json +{ + "parameters": { + "userId": { + "$ref": "#/components/parameters/userId" + } + }, + "bindings": { + "kafka": { + "partitions": 10, + "replicas": 3 + } + } +} +``` + + +```yaml +parameters: + userId: + $ref: '#/components/parameters/userId' +bindings: + kafka: + partitions: 10 + replicas: 3 ``` #### Channel Address Expressions @@ -1619,6 +1678,7 @@ Field Name | Type | Description tags | Map[`string`, [Tag Object](#tagObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Tag Objects](#tagObject). operationTraits | Map[`string`, [Operation Trait Object](#operationTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Trait Objects](#operationTraitObject). messageTraits | Map[`string`, [Message Trait Object](#messageTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Trait Objects](#messageTraitObject). + channelTraits | Map[`string`, [Channel Trait Object](#channelTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Trait Objects](#channelTraitObject). serverBindings | Map[`string`, [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Bindings Objects](#serverBindingsObject). channelBindings | Map[`string`, [Channel Bindings Object](#channelBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Bindings Objects](#channelBindingsObject). operationBindings | Map[`string`, [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Bindings Objects](#operationBindingsObject). @@ -1769,6 +1829,21 @@ my.org.User } } } + }, + "channelTraits": { + "kafkaTopicsCommon": { + "parameters": { + "userId": { + "$ref": "#/components/parameters/userId" + } + }, + "bindings": { + "kafka": { + "partitions": 10, + "replicas": 3 + } + } + } } } } @@ -1865,6 +1940,15 @@ components: type: integer minimum: 0 maximum: 100 + channelTraits: + kafkaTopicsCommon: + parameters: + userId: + $ref: '#/components/parameters/userId' + bindings: + kafka: + partitions: 10 + replicas: 3 ``` #### Multi Format Schema Object