feat: add new channels object (#827)

asyncapi · Sep 21, 2022 · 8805c88 · 8805c88
1 parent caf8c75
commit 8805c88
Showing 1 changed file with 101 additions and 97 deletions.
diff --git 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)
@@ -162,7 +162,7 @@ Field Name | Type | Description
 <a name="A2SInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed.
 <a name="A2SServers"></a>servers | [Servers Object](#serversObject) | Provides connection details of servers.
 <a name="A2SDefaultContentType"></a>defaultContentType | [Default Content Type](#defaultContentTypeString) | Default content type to use when encoding/decoding a message's payload.
-<a name="A2SChannels"></a>channels | [Channels Object](#channelsObject) | **Required** The available channels and messages for the API.
+<a name="A2SChannels"></a>channels | [Channels Object](#channelsObject) | The channels used by this [application](#definitionsApplication).
 <a name="A2SComponents"></a>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).
 <a name="A2STags"></a>tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique.
 <a name="A2SExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
@@ -529,23 +529,22 @@ defaultContentType: application/json
 
 #### <a name="channelsObject"></a>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
 ---|:---:|---
-<a name="channelsObjectChannel"></a>{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.
+<a name="channelsObjectChannel"></a>{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": {
+ "userSignedUp": {
+ "address": "user.signedup",
+ "messages": {
+ "userSignedUp": {
  "$ref": "#/components/messages/userSignedUp"
  }
  }
@@ -554,142 +553,147 @@ Field Pattern | Type | Description
 ```
 
 ```yaml
-user/signedup:
- subscribe:
- message:
- $ref: "#/components/messages/userSignedUp"
+userSignedUp:
+ address: 'user.signedup'
+ messages:
+ userSignedUp:
+ $ref: '#/components/messages/userSignedUp'
 ```
 
 
 
 
-#### <a name="channelItemObject"></a>Channel Item Object
+#### <a name="channelObject"></a>Channel Object
 
-Describes the operations available on a single channel.
+Describes a shared communication channel.
 
 ##### Fixed Fields
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="channelItemObjectDescription"></a>description | `string` | An optional description of this channel item. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
-<a name="channelItemObjectServers"></a>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).
-<a name="channelItemObjectSubscribe"></a>subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation, which defines the messages produced by the application and sent to the channel.
-<a name="channelItemObjectPublish"></a>publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation, which defines the messages consumed by the application from the channel.
-<a name="channelItemObjectParameters"></a>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)).
-<a name="channelItemObjectBindings"></a>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.
+<a name="channelObjectAddress"></a>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).
+<a name="channelObjectMessages"></a>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.**
+<a name="channelObjectDescription"></a>description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
+<a name="channelObjectServers"></a>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.
+<a name="channelObjectParameters"></a>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).
+<a name="channelObjectBindings"></a>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.
+<a name="channelObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels.
+<a name="channelObjectExternalDocs"></a>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"
- }
- }
- }
+ "address": "users.{userId}",
+ "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": [
+ { "$ref": "#/servers/rabbitmqInProd" },
+ { "$ref": "#/servers/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
-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"
+address: 'users.{userId}'
+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:
+ - $ref: '#/servers/rabbitmqInProd'
+ - $ref: '#/servers/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:
+#### <a name="channelAddressExpressions"></a>Channel Address Expressions
+
+Channel addresses MAY contain expressions that can be used to define dynamic values.
+
+Expressions MUST be composed by a name enclosed in curly braces (`{` and `}`). E.g., `{userId}`.
+
+
+
+
+
+#### <a name="messagesObject"></a>Messages Object
+
+Describes a map of messages included in a channel.
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+<a name="messagesObjectId"></a>`{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"
- }
+ "userSignedUp": {
+ "$ref": "#/components/messages/userSignedUp"
  },
- "bindings": {
- "amqp": {
- "is": "queue"
- }
+ "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
+userSignedUp:
+ $ref: '#/components/messages/userSignedUp'
+userCompletedOrder:
+ $ref: '#/components/messages/userCompletedOrder'
 ```
 
 
@@ -1464,7 +1468,7 @@ Field Name | Type | Description
 ---|:---|--- 
 <a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject).
 <a name="componentsServers"></a> servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject).
-<a name="componentsChannels"></a> channels | Map[`string`, [Channel Item Object](#channelItemObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Item Objects](#channelItemObject).
+<a name="componentsChannels"></a> channels | Map[`string`, [Channel Object](#channelObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Objects](#channelObject).
 <a name="componentsServerVariables"></a> serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). 
 <a name="componentsMessages"></a> messages | Map[`string`, [Message Object](#messageObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Objects](#messageObject).
 <a name="componentsSecuritySchemes"></a> securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
@@ -2554,6 +2558,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.