diff --git a/README.md b/README.md index 262a30690..bde789ce9 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,8 @@ The latest draft specification can be found at [spec/asyncapi.md](./spec/asyncapi.md) which tracks the latest commit to the master branch in this repository. -* [Version 2.1.0](https://github.com/asyncapi/spec/blob/v2.1.0/spec/asyncapi.md) (latest) +* [Version 2.2.0](https://github.com/asyncapi/spec/blob/v2.2.0/spec/asyncapi.md) (latest) +* [Version 2.1.0](https://github.com/asyncapi/spec/blob/v2.1.0/spec/asyncapi.md) * [Version 2.0.0](https://github.com/asyncapi/spec/blob/2.0.0/versions/2.0.0/asyncapi.md) * [Version 1.2.0](https://github.com/asyncapi/spec/blob/1.2.0/README.md) (deprecated) * [Version 1.1.0](https://github.com/asyncapi/spec/blob/1.1.0/README.md) (deprecated) diff --git a/examples/anyof.yml b/examples/anyof.yml index 6efe77699..73a56e6b8 100644 --- a/examples/anyof.yml +++ b/examples/anyof.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' info: title: AnyOf example version: '1.0.0' diff --git a/examples/application-headers.yml b/examples/application-headers.yml index 9d0bbbf3b..ff8874f14 100644 --- a/examples/application-headers.yml +++ b/examples/application-headers.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' info: title: Application Headers example version: '1.0.0' diff --git a/examples/correlation-id.yml b/examples/correlation-id.yml index fd0c49878..e7255791a 100644 --- a/examples/correlation-id.yml +++ b/examples/correlation-id.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' info: title: Correlation ID Example version: '1.0.0' diff --git a/examples/gitter-streaming.yml b/examples/gitter-streaming.yml index bb8b76ffa..87e5a65a2 100644 --- a/examples/gitter-streaming.yml +++ b/examples/gitter-streaming.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' id: 'urn:com:gitter:streaming:api' info: title: Gitter Streaming API diff --git a/examples/mercure.yml b/examples/mercure.yml index 63e2acc66..239f27e38 100644 --- a/examples/mercure.yml +++ b/examples/mercure.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' info: title: Mercure Hub Example version: '1.0.0' diff --git a/examples/not.yml b/examples/not.yml index b6dbc76c1..ae61a9173 100644 --- a/examples/not.yml +++ b/examples/not.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' info: title: Not example version: '1.0.0' diff --git a/examples/oneof.yml b/examples/oneof.yml index 8d7ff8356..94f61fc7f 100644 --- a/examples/oneof.yml +++ b/examples/oneof.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' info: title: OneOf example version: '1.0.0' diff --git a/examples/rpc-client.yml b/examples/rpc-client.yml index 6c0f31745..cf875bb24 100644 --- a/examples/rpc-client.yml +++ b/examples/rpc-client.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' id: 'urn:rpc:example:client' defaultContentType: application/json diff --git a/examples/rpc-server.yml b/examples/rpc-server.yml index dc9b0b02f..181ef8f31 100644 --- a/examples/rpc-server.yml +++ b/examples/rpc-server.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' id: 'urn:rpc:example:server' defaultContentType: application/json diff --git a/examples/simple.yml b/examples/simple.yml index 79e1ae6c1..cbcf47ca8 100644 --- a/examples/simple.yml +++ b/examples/simple.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' info: title: Account Service version: 1.0.0 diff --git a/examples/slack-rtm.yml b/examples/slack-rtm.yml index b3cdba314..e600e0b73 100644 --- a/examples/slack-rtm.yml +++ b/examples/slack-rtm.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' id: 'urn:com:slack:rtm:api' info: title: Slack Real Time Messaging API diff --git a/examples/streetlights-kafka.yml b/examples/streetlights-kafka.yml index 95ff29e96..ee8437c40 100644 --- a/examples/streetlights-kafka.yml +++ b/examples/streetlights-kafka.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' info: title: Streetlights Kafka API version: '1.0.0' diff --git a/examples/streetlights-mqtt.yml b/examples/streetlights-mqtt.yml index 36d48b8ad..5667034d9 100644 --- a/examples/streetlights-mqtt.yml +++ b/examples/streetlights-mqtt.yml @@ -1,4 +1,4 @@ -asyncapi: '2.1.0' +asyncapi: '2.2.0' info: title: Streetlights MQTT API version: '1.0.0' diff --git a/examples/websocket-gemini.yml b/examples/websocket-gemini.yml index b6dc498fb..cb1c3702a 100644 --- a/examples/websocket-gemini.yml +++ b/examples/websocket-gemini.yml @@ -12,7 +12,7 @@ # - Live stream about topics mentioned in part 1 and 2 articles: https://www.youtube.com/watch?v=8tFBcf31e_c # -asyncapi: '2.1.0' +asyncapi: '2.2.0' # # Overal information for users of the application diff --git a/spec/asyncapi.md b/spec/asyncapi.md index c6618e953..4887d56ad 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -4,7 +4,7 @@ Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). Mainly because **it's a great work** and we want to keep as much compatibility as possible with the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification). -#### Version 2.1.0 +#### Version 2.2.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). @@ -99,7 +99,7 @@ A message is the mechanism by which information is exchanged via a channel betwe A channel is an addressable component, made available by the server, for the organization of [messages](#definitionsMessage). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume messages from channels. Servers MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the server implementation, the channel MAY be included in the message via protocol-defined headers. #### Protocol -A protocol is the mechanism (wireline protocol or API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, MQTT, STOMP, Mercure, WebSocket. +A protocol is the mechanism (wireline protocol or API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, STOMP, Mercure, WebSocket. #### Bindings A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only. @@ -351,7 +351,7 @@ An object representing a message broker, a server or any other kind of computer Field Name | Type | Description ---|:---:|--- url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. -protocol | `string` | **REQUIRED**. The protocol this URL supports for connection. Supported protocol include, but are not limited to: `amqp`, `amqps`, `http`, `https`, `ibmmq`, `jms`, `kafka`, `kafka-secure`, `mqtt`, `secure-mqtt`, `stomp`, `stomps`, `ws`, `wss`, `mercure`. +protocol | `string` | **REQUIRED**. The protocol this URL supports for connection. Supported protocol include, but are not limited to: `amqp`, `amqps`, `http`, `https`, `ibmmq`, `jms`, `kafka`, `kafka-secure`, `anypointmq`, `mqtt`, `secure-mqtt`, `stomp`, `stomps`, `ws`, `wss`, `mercure`. protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. @@ -563,6 +563,7 @@ Field Name | Type | Description ---|:---:|--- $ref | `string` | Allows for an external definition of this channel item. The referenced structure MUST be in the format of a [Channel Item Object](#channelItemObject). If there are conflicts between the referenced definition and this Channel Item's definition, the behavior is *undefined*. 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)). @@ -646,6 +647,40 @@ subscribe: ``` +Using explicit by-name references to the servers on which the channel is available: + +```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" + } + } +} +``` + +```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 +``` @@ -897,6 +932,7 @@ Field Name | Type | Description `http` | [HTTP Server Binding](https://github.com/asyncapi/bindings/blob/master/http#server) | Protocol-specific information for an HTTP server. `ws` | [WebSockets Server Binding](https://github.com/asyncapi/bindings/blob/master/websockets#server) | Protocol-specific information for a WebSockets server. `kafka` | [Kafka Server Binding](https://github.com/asyncapi/bindings/blob/master/kafka#server) | Protocol-specific information for a Kafka server. +`anypointmq` | [Anypoint MQ Server Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq#server) | Protocol-specific information for an Anypoint MQ server. `amqp` | [AMQP Server Binding](https://github.com/asyncapi/bindings/blob/master/amqp#server) | Protocol-specific information for an AMQP 0-9-1 server. `amqp1` | [AMQP 1.0 Server Binding](https://github.com/asyncapi/bindings/blob/master/amqp1#server) | Protocol-specific information for an AMQP 1.0 server. `mqtt` | [MQTT Server Binding](https://github.com/asyncapi/bindings/blob/master/mqtt#server) | Protocol-specific information for an MQTT server. @@ -925,6 +961,7 @@ Field Name | Type | Description `http` | [HTTP Channel Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#channel) | Protocol-specific information for an HTTP channel. `ws` | [WebSockets Channel Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#channel) | Protocol-specific information for a WebSockets channel. `kafka` | [Kafka Channel Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#channel) | Protocol-specific information for a Kafka channel. +`anypointmq` | [Anypoint MQ Channel Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#channel) | Protocol-specific information for an Anypoint MQ channel. `amqp` | [AMQP Channel Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#channel) | Protocol-specific information for an AMQP 0-9-1 channel. `amqp1` | [AMQP 1.0 Channel Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#channel) | Protocol-specific information for an AMQP 1.0 channel. `mqtt` | [MQTT Channel Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#channel) | Protocol-specific information for an MQTT channel. @@ -953,6 +990,7 @@ Field Name | Type | Description `http` | [HTTP Operation Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#operation) | Protocol-specific information for an HTTP operation. `ws` | [WebSockets Operation Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#operation) | Protocol-specific information for a WebSockets operation. `kafka` | [Kafka Operation Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#operation) | Protocol-specific information for a Kafka operation. +`anypointmq` | [Anypoint MQ Operation Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#operation) | Protocol-specific information for an Anypoint MQ operation. `amqp` | [AMQP Operation Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#operation) | Protocol-specific information for an AMQP 0-9-1 operation. `amqp1` | [AMQP 1.0 Operation Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#operation) | Protocol-specific information for an AMQP 1.0 operation. `mqtt` | [MQTT Operation Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#operation) | Protocol-specific information for an MQTT operation. @@ -981,6 +1019,7 @@ Field Name | Type | Description `http` | [HTTP Message Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#message) | Protocol-specific information for an HTTP message, i.e., a request or a response. `ws` | [WebSockets Message Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#message) | Protocol-specific information for a WebSockets message. `kafka` | [Kafka Message Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#message) | Protocol-specific information for a Kafka message. +`anypointmq` | [Anypoint MQ Message Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#message) | Protocol-specific information for an Anypoint MQ message. `amqp` | [AMQP Message Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#message) | Protocol-specific information for an AMQP 0-9-1 message. `amqp1` | [AMQP 1.0 Message Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#message) | Protocol-specific information for an AMQP 1.0 message. `mqtt` | [MQTT Message Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#message) | Protocol-specific information for an MQTT message. @@ -1033,7 +1072,7 @@ The following table contains a set of values that every implementation MUST supp Name | Allowed values | Notes ---|:---:|--- -[AsyncAPI 2.1.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.1.0`, `application/vnd.aai.asyncapi+json;version=2.1.0`, `application/vnd.aai.asyncapi+yaml;version=2.1.0` | This is the default when a `schemaFormat` is not provided. +[AsyncAPI 2.2.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.2.0`, `application/vnd.aai.asyncapi+json;version=2.2.0`, `application/vnd.aai.asyncapi+yaml;version=2.2.0` | This is the default when a `schemaFormat` is not provided. [JSON Schema Draft 07](https://json-schema.org/specification-links.html#draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | The following table contains a set of values that every implementation is RECOMMENDED to support.