Skip to content

Commit

Permalink
feat: add new channels object (#827)
Browse files Browse the repository at this point in the history
  • Loading branch information
@fmvilas
fmvilas committed Sep 21, 2022
1 parent 3c59fa6 commit 624ad52
Showing 1 changed file with 99 additions and 95 deletions.
194 changes: 99 additions & 95 deletions spec/asyncapi.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,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)
Expand Down Expand Up @@ -167,7 +167,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.
Expand Down Expand Up @@ -534,23 +534,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"
}
}
Expand All @@ -559,142 +558,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 MAY 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'
```


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

0 comments on commit 624ad52

Please sign in to comment.