From 2f92333893fcd77f3b89b37f5e5707a7edb31c60 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Sat, 27 Aug 2022 03:48:05 +0200 Subject: [PATCH 01/11] feat: add new channels object --- spec/asyncapi.md | 240 ++++++++++++++++++++++++++--------------------- 1 file changed, 135 insertions(+), 105 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 8a4c431de..d613606e1 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -56,7 +56,7 @@ It means that the [application](#definitionsApplication) allows [consumers](#def - [Server Variable Object](#serverVariableObject) - [Default Content Type](#defaultContentTypeString) - [Channels Object](#channelsObject) - - [Channel Item Object](#channelItemObject) + - [Channel Object](#channelObject) - [Operation Object](#operationObject) - [Operation Trait Object](#operationTraitObject) - [Message Object](#messageObject) @@ -529,24 +529,26 @@ defaultContentType: application/json #### Channels Object -Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers. - -Channels are also known as "topics", "routing keys", "event types" or "paths". +An object containing all the [Channel Object](#channelObject) definitions the [Application](#definitionsApplication) MUST use during runtime. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- -{channel} | [Channel Item Object](#channelItemObject) \| [Reference Object](#referenceObject) | A relative path to an individual channel. The field name MUST be in the form of a [RFC 6570 URI template](https://tools.ietf.org/html/rfc6570). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channelBindingsObject) to define them. +{channelId} | [Channel Object](#channelObject) \| [Reference Object](#referenceObject) | An identifier for the described channel. The `channelId` value is **case-sensitive**. Tools and libraries MAY use the `channelId` to uniquely identify a channel, therefore, it is RECOMMENDED to follow common programming naming conventions. ##### Channels Object Example ```json { - "user/signedup": { - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" + "channels": { + "userSignedUp": { + "address": "user.signedup", + "addressDelimiter": ".", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + } } } } @@ -554,59 +556,77 @@ Field Pattern | Type | Description ``` ```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignedUp" +channels: + userSignedUp: + address: 'user.signedup' + addressDelimiter: '.' + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' ``` -#### Channel Item Object +#### Channel Object -Describes the operations available on a single channel. +Describes a shared communication channel. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -description | `string` | An optional description of this channel item. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). -subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation, which defines the messages produced by the application and sent to the channel. -publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation, which defines the messages consumed by the application from the channel. -parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)). -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. +address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Pattern-Matching Expressions](#channelPatternMatchingExpressions). +addressDelimiter | `string` | An optional string to use for delimiting the address in multiple logical sections. E.g., the AMQP protocol uses the `.` (dot) character and MQTT uses the `/` (slash) character. +messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the message objects defined in this map.** +description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). +parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Pattern-Matching Expressions](channelPatternMatchingExpressions). +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. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. +externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this channel. + This object can be extended with [Specification Extensions](#specificationExtensions). -##### Channel Item Object Example +##### Channel Object Example ```json { - "description": "This channel is used to exchange messages about users signing up", - "subscribe": { - "summary": "A user signed up.", - "message": { - "description": "A longer description of the message", - "payload": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/user" - }, - "signup": { - "$ref": "#/components/schemas/signup" + "channels": { + "userEvents": { + "address": "users.{userId}", + "addressDelimiter": ".", + "description": "This channel is used to exchange messages about user events.", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" + } + }, + "parameters": { + "userId": { + "$ref": "#/components/parameters/userId" + } + }, + "servers": ["rabbitmqInProd", "rabbitmqInStaging"], + "bindings": { + "amqp": { + "is": "queue", + "queue": { + "exclusive": true } } - } - } - }, - "bindings": { - "amqp": { - "is": "queue", - "queue": { - "exclusive": true + }, + "tags": [{ + "name": "user", + "description": "User-related messages" + }], + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" } } } @@ -614,82 +634,92 @@ This object can be extended with [Specification Extensions](#specificationExtens ``` ```yaml -description: This channel is used to exchange messages about users signing up -subscribe: - summary: A user signed up. - message: - description: A longer description of the message - payload: - type: object - properties: - user: - $ref: "#/components/schemas/user" - signup: - $ref: "#/components/schemas/signup" -bindings: - amqp: - is: queue - queue: - exclusive: true +channels: + userEvents: + address: 'users.{userId}' + addressDelimiter: '.' + description: This channel is used to exchange messages about user events. + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' + parameters: + userId: + $ref: '#/components/parameters/userId' + servers: + - rabbitmqInProd + - rabbitmqInStaging + bindings: + amqp: + is: queue + queue: + exclusive: true + tags: + - name: user + description: User-related messages + externalDocs: + description: 'Find more info here' + url: 'https://example.com' ``` -Using `oneOf` to specify multiple messages per operation: -```json -{ - "subscribe": { - "message": { - "oneOf": [ - { "$ref": "#/components/messages/signup" }, - { "$ref": "#/components/messages/login" } - ] - } - } -} -``` -```yaml -subscribe: - message: - oneOf: - - $ref: '#/components/messages/signup' - - $ref: '#/components/messages/login' -``` -Using explicit by-name references to the servers on which the channel is available: +#### Channel Pattern-Matching Expressions + +Channel addresses MAY contain pattern-matching expressions that can be used to define dynamic values. + +Pattern-matching expressions MUST be composed by a name enclosed in curly braces (`{` and `}`). E.g., `{userId}`. + +When the channel address contains [delimiters](#channelObjectAddressDelimiter), pattern-matching expressions MUST be surrounded by either the delimiters, the beginning of the string, or the end of the string. E.g., assuming a `.` (dot) delimiter, `users.{userId}` is correct but `users.id{userId}` is not. + + + + + +#### Messages Object + +Describes a map of messages included in a channel. + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +`{messageId}` | [Message Object](#messageObject) \| [Reference Object](#referenceObject) | The key represents the message identifier. The `messageId` value is **case-sensitive**. Tools and libraries MAY use the `messageId` value to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. + +##### Messages Object Example ```json { - "description": "This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments.", - "servers": [ - "rabbitmqBrokerInProd", - "rabbitmqBrokerInStaging", - ], - "subscribe": { - "message": { - "$ref": "#/components/messages/WebUICommand" - } - }, - "bindings": { - "amqp": { - "is": "queue" + "channels": { + "userEvents": { + "address": "users.{userId}", + "addressDelimiter": ".", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" + } + } } } } ``` ```yaml -description: This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments. -servers: - - rabbitmqBrokerInProd - - rabbitmqBrokerInStaging -subscribe: - message: - $ref: "#/components/messages/WebUICommand" -bindings: - amqp: - is: queue +channels: + userEvents: + address: 'users.{userId}' + addressDelimiter: '.' + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' ``` @@ -1464,7 +1494,7 @@ Field Name | Type | Description ---|:---|--- schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject). - channels | Map[`string`, [Channel Item Object](#channelItemObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Item Objects](#channelItemObject). + channels | Map[`string`, [Channel Object](#channelObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Objects](#channelObject). serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). messages | Map[`string`, [Message Object](#messageObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Objects](#messageObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). From 34844d847f399f78321559a23d3e7c51f203a80e Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Sat, 27 Aug 2022 03:54:48 +0200 Subject: [PATCH 02/11] change the name of pattern-matching expressions --- spec/asyncapi.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index d613606e1..302cfc0d0 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -576,12 +576,12 @@ Describes a shared communication channel. Field Name | Type | Description ---|:---:|--- -address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Pattern-Matching Expressions](#channelPatternMatchingExpressions). +address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions). addressDelimiter | `string` | An optional string to use for delimiting the address in multiple logical sections. E.g., the AMQP protocol uses the `.` (dot) character and MQTT uses the `/` (slash) character. messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the message objects defined in this map.** description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). -parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Pattern-Matching Expressions](channelPatternMatchingExpressions). +parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](channelAddressExpressions). 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. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this channel. @@ -667,13 +667,13 @@ channels: -#### Channel Pattern-Matching Expressions +#### Channel Address Expressions -Channel addresses MAY contain pattern-matching expressions that can be used to define dynamic values. +Channel addresses MAY contain expressions that can be used to define dynamic values. -Pattern-matching expressions MUST be composed by a name enclosed in curly braces (`{` and `}`). E.g., `{userId}`. +Expressions MUST be composed by a name enclosed in curly braces (`{` and `}`). E.g., `{userId}`. -When the channel address contains [delimiters](#channelObjectAddressDelimiter), pattern-matching expressions MUST be surrounded by either the delimiters, the beginning of the string, or the end of the string. E.g., assuming a `.` (dot) delimiter, `users.{userId}` is correct but `users.id{userId}` is not. +When the channel address contains [delimiters](#channelObjectAddressDelimiter), the expressions MUST be surrounded by either the delimiters, the beginning of the string, or the end of the string. E.g., assuming a `.` (dot) delimiter, `users.{userId}` is correct but `users.id{userId}` is not. From 9273d4a8a218fada1b92e560b3680fe2ce51d204 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Sat, 27 Aug 2022 03:58:02 +0200 Subject: [PATCH 03/11] Make channels optional --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 302cfc0d0..817131ecc 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -162,7 +162,7 @@ Field Name | Type | Description info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. servers | [Servers Object](#serversObject) | Provides connection details of servers. defaultContentType | [Default Content Type](#defaultContentTypeString) | Default content type to use when encoding/decoding a message's payload. -channels | [Channels Object](#channelsObject) | **Required** The available channels and messages for the API. +channels | [Channels Object](#channelsObject) | The channels used by this [application](#definitionsApplication). components | [Components Object](#componentsObject) | An element to hold various reusable objects for the specification. Everything that is defined inside this object represents a resource that MAY or MAY NOT be used in the rest of the document and MAY or MAY NOT be used by the implemented [Application](#definitionsApplication). tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. From e4b19f0f6b39462a50f2e5277d02a4f3c7ef139f Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Sat, 27 Aug 2022 04:01:02 +0200 Subject: [PATCH 04/11] fix typo in link to channel expressions --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 817131ecc..d5a332897 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -581,7 +581,7 @@ Field Name | Type | Description messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the message objects defined in this map.** description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). -parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](channelAddressExpressions). +parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](#channelAddressExpressions). 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. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this channel. From d6e5521cba9bac400c3b6a03095102916f989512 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Sat, 27 Aug 2022 04:04:26 +0200 Subject: [PATCH 05/11] fix broken links --- spec/asyncapi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index d5a332897..a05731e80 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -2584,6 +2584,6 @@ string | `string` | | | byte | `string` | `byte` | base64 encoded characters binary | `string` | `binary` | any sequence of octets boolean | `boolean` | | | -date | `string` | `date` | As defined by `full-date` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) -dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14) +date | `string` | `date` | As defined by `full-date` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) +dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) password | `string` | `password` | Used to hint UIs the input needs to be obscured. From de70f32ab2c75584223f8e8a93194bdd190ad7b1 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Fri, 9 Sep 2022 17:44:00 +0200 Subject: [PATCH 06/11] Remove context from examples --- spec/asyncapi.md | 176 +++++++++++++++++++++-------------------------- 1 file changed, 77 insertions(+), 99 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index a05731e80..d16997f31 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -541,14 +541,12 @@ Field Pattern | Type | Description ```json { - "channels": { - "userSignedUp": { - "address": "user.signedup", - "addressDelimiter": ".", - "messages": { - "userSignedUp": { - "$ref": "#/components/messages/userSignedUp" - } + "userSignedUp": { + "address": "user.signedup", + "addressDelimiter": ".", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" } } } @@ -556,13 +554,12 @@ Field Pattern | Type | Description ``` ```yaml -channels: - userSignedUp: - address: 'user.signedup' - addressDelimiter: '.' - messages: - userSignedUp: - $ref: '#/components/messages/userSignedUp' +userSignedUp: + address: 'user.signedup' + addressDelimiter: '.' + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' ``` @@ -578,7 +575,7 @@ Field Name | Type | Description ---|:---:|--- address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions). addressDelimiter | `string` | An optional string to use for delimiting the address in multiple logical sections. E.g., the AMQP protocol uses the `.` (dot) character and MQTT uses the `/` (slash) character. -messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the message objects defined in this map.** +messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#messageObject) defined in this map.** description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](#channelAddressExpressions). @@ -593,74 +590,68 @@ This object can be extended with [Specification Extensions](#specificationExtens ```json { - "channels": { - "userEvents": { - "address": "users.{userId}", - "addressDelimiter": ".", - "description": "This channel is used to exchange messages about user events.", - "messages": { - "userSignedUp": { - "$ref": "#/components/messages/userSignedUp" - }, - "userCompletedOrder": { - "$ref": "#/components/messages/userCompletedOrder" - } - }, - "parameters": { - "userId": { - "$ref": "#/components/parameters/userId" - } - }, - "servers": ["rabbitmqInProd", "rabbitmqInStaging"], - "bindings": { - "amqp": { - "is": "queue", - "queue": { - "exclusive": true - } - } - }, - "tags": [{ - "name": "user", - "description": "User-related messages" - }], - "externalDocs": { - "description": "Find more info here", - "url": "https://example.com" + "address": "users.{userId}", + "addressDelimiter": ".", + "description": "This channel is used to exchange messages about user events.", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" + } + }, + "parameters": { + "userId": { + "$ref": "#/components/parameters/userId" + } + }, + "servers": ["rabbitmqInProd", "rabbitmqInStaging"], + "bindings": { + "amqp": { + "is": "queue", + "queue": { + "exclusive": true } } + }, + "tags": [{ + "name": "user", + "description": "User-related messages" + }], + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" } } ``` ```yaml -channels: - userEvents: - address: 'users.{userId}' - addressDelimiter: '.' - description: This channel is used to exchange messages about user events. - messages: - userSignedUp: - $ref: '#/components/messages/userSignedUp' - userCompletedOrder: - $ref: '#/components/messages/userCompletedOrder' - parameters: - userId: - $ref: '#/components/parameters/userId' - servers: - - rabbitmqInProd - - rabbitmqInStaging - bindings: - amqp: - is: queue - queue: - exclusive: true - tags: - - name: user - description: User-related messages - externalDocs: - description: 'Find more info here' - url: 'https://example.com' +address: 'users.{userId}' +addressDelimiter: '.' +description: This channel is used to exchange messages about user events. +messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' +parameters: + userId: + $ref: '#/components/parameters/userId' +servers: + - rabbitmqInProd + - rabbitmqInStaging +bindings: + amqp: + is: queue + queue: + exclusive: true +tags: + - name: user + description: User-related messages +externalDocs: + description: 'Find more info here' + url: 'https://example.com' ``` @@ -693,33 +684,20 @@ Field Pattern | Type | Description ```json { - "channels": { - "userEvents": { - "address": "users.{userId}", - "addressDelimiter": ".", - "messages": { - "userSignedUp": { - "$ref": "#/components/messages/userSignedUp" - }, - "userCompletedOrder": { - "$ref": "#/components/messages/userCompletedOrder" - } - } - } + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" } } ``` ```yaml -channels: - userEvents: - address: 'users.{userId}' - addressDelimiter: '.' - messages: - userSignedUp: - $ref: '#/components/messages/userSignedUp' - userCompletedOrder: - $ref: '#/components/messages/userCompletedOrder' +userSignedUp: + $ref: '#/components/messages/userSignedUp' +userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' ``` From 40425941fa987c3aca1cd240d81a2af6434f77b3 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Fri, 9 Sep 2022 18:19:34 +0200 Subject: [PATCH 07/11] Remove addressDelimiter restrictions --- spec/asyncapi.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index d16997f31..aa72da2dd 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -543,7 +543,6 @@ Field Pattern | Type | Description { "userSignedUp": { "address": "user.signedup", - "addressDelimiter": ".", "messages": { "userSignedUp": { "$ref": "#/components/messages/userSignedUp" @@ -556,7 +555,6 @@ Field Pattern | Type | Description ```yaml userSignedUp: address: 'user.signedup' - addressDelimiter: '.' messages: userSignedUp: $ref: '#/components/messages/userSignedUp' @@ -574,7 +572,6 @@ Describes a shared communication channel. Field Name | Type | Description ---|:---:|--- address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions). -addressDelimiter | `string` | An optional string to use for delimiting the address in multiple logical sections. E.g., the AMQP protocol uses the `.` (dot) character and MQTT uses the `/` (slash) character. messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#messageObject) defined in this map.** description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). @@ -591,7 +588,6 @@ This object can be extended with [Specification Extensions](#specificationExtens ```json { "address": "users.{userId}", - "addressDelimiter": ".", "description": "This channel is used to exchange messages about user events.", "messages": { "userSignedUp": { @@ -628,7 +624,6 @@ This object can be extended with [Specification Extensions](#specificationExtens ```yaml address: 'users.{userId}' -addressDelimiter: '.' description: This channel is used to exchange messages about user events. messages: userSignedUp: @@ -664,8 +659,6 @@ Channel addresses MAY contain expressions that can be used to define dynamic val Expressions MUST be composed by a name enclosed in curly braces (`{` and `}`). E.g., `{userId}`. -When the channel address contains [delimiters](#channelObjectAddressDelimiter), the expressions MUST be surrounded by either the delimiters, the beginning of the string, or the end of the string. E.g., assuming a `.` (dot) delimiter, `users.{userId}` is correct but `users.id{userId}` is not. - From 82a335fd61fa376980c2460c5f5cb54021bca183 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Fri, 9 Sep 2022 18:24:12 +0200 Subject: [PATCH 08/11] Add 429 and 200 status codes to mlc action --- mlc_config.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mlc_config.json b/mlc_config.json index 01833db7f..0169a1b03 100644 --- a/mlc_config.json +++ b/mlc_config.json @@ -15,5 +15,6 @@ { "pattern": "^https://github.com/asyncapi/spec/blob/.*.md$" } - ] + ], + "aliveStatusCodes": [429, 200] } From 35d5adf35983f3098f7f95721d9b5678c1d457f4 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Fri, 9 Sep 2022 18:30:25 +0200 Subject: [PATCH 09/11] Remove aliveStatusCodes from mlc config --- mlc_config.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/mlc_config.json b/mlc_config.json index 0169a1b03..01833db7f 100644 --- a/mlc_config.json +++ b/mlc_config.json @@ -15,6 +15,5 @@ { "pattern": "^https://github.com/asyncapi/spec/blob/.*.md$" } - ], - "aliveStatusCodes": [429, 200] + ] } From 58e9d0725a2883d267a4132ce8fefc251d85fd09 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Mon, 12 Sep 2022 12:53:17 +0200 Subject: [PATCH 10/11] Change servers to use $refs --- spec/asyncapi.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index aa72da2dd..d873bf13f 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -574,7 +574,7 @@ Field Name | Type | Description address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions). messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#messageObject) defined in this map.** description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). +servers | [[Reference Object](#referenceObject)] | An array `$ref` pointers to the definition of the servers in which this channel is available. If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#serverObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](#channelAddressExpressions). 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. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. @@ -602,7 +602,10 @@ This object can be extended with [Specification Extensions](#specificationExtens "$ref": "#/components/parameters/userId" } }, - "servers": ["rabbitmqInProd", "rabbitmqInStaging"], + "servers": [ + { "$ref": "#/servers/rabbitmqInProd" }, + { "$ref": "#/servers/rabbitmqInStaging" } + ], "bindings": { "amqp": { "is": "queue", @@ -634,8 +637,8 @@ parameters: userId: $ref: '#/components/parameters/userId' servers: - - rabbitmqInProd - - rabbitmqInStaging + - $ref: '#/servers/rabbitmqInProd' + - $ref: '#/servers/rabbitmqInStaging' bindings: amqp: is: queue From f7a0a796d302471ac2f997873e5a08b4fd0a1456 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Wed, 21 Sep 2022 10:26:21 +0200 Subject: [PATCH 11/11] Fix typo Co-authored-by: Jonas Lagoni --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index d873bf13f..d65fd6b9e 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -574,7 +574,7 @@ Field Name | Type | Description address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions). messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#messageObject) defined in this map.** 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 `$ref` pointers to the definition of the servers in which this channel is available. If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#serverObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +servers | [[Reference Object](#referenceObject)] | An array of `$ref` pointers to the definition of the servers in which this channel is available. If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#serverObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](#channelAddressExpressions). 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. tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels.