diff --git a/.github/workflows/if-nodejs-release.yml b/.github/workflows/if-nodejs-release.yml index bc5b5376..4a34feb0 100644 --- a/.github/workflows/if-nodejs-release.yml +++ b/.github/workflows/if-nodejs-release.yml @@ -9,12 +9,9 @@ on: branches: - master # below lines are not enough to have release supported for these branches - # make sure configuration of `semantic-release` package mentiones these branches - - next - - next-major - - beta - - alpha - - '**-release' # custom + # make sure configuration of `semantic-release` package mentions these branches + - next-spec + - next-major-spec jobs: diff --git a/README.md b/README.md index c1588d43..c3079baa 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,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. The human-readable markdown file is the source of truth for the specification. -- [Version 2.4.0](https://github.com/asyncapi/spec/blob/v2.4.0/spec/asyncapi.md) (latest) +- [Version 2.5.0](https://github.com/asyncapi/spec/blob/v2.5.0/spec/asyncapi.md) (latest) +- [Version 2.4.0](https://github.com/asyncapi/spec/blob/v2.4.0/spec/asyncapi.md) - [Version 2.3.0](https://github.com/asyncapi/spec/blob/v2.3.0/spec/asyncapi.md) - [Version 2.2.0](https://github.com/asyncapi/spec/blob/v2.2.0/spec/asyncapi.md) - [Version 2.1.0](https://github.com/asyncapi/spec/blob/v2.1.0/spec/asyncapi.md) diff --git a/examples/anyof.yml b/examples/anyof.yml index b1779975..a73ac409 100644 --- a/examples/anyof.yml +++ b/examples/anyof.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' info: title: AnyOf example version: '1.0.0' diff --git a/examples/application-headers.yml b/examples/application-headers.yml index c66bcef3..0ebe339d 100644 --- a/examples/application-headers.yml +++ b/examples/application-headers.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' info: title: Application Headers example version: '1.0.0' diff --git a/examples/correlation-id.yml b/examples/correlation-id.yml index f501c59a..33bb2770 100644 --- a/examples/correlation-id.yml +++ b/examples/correlation-id.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' info: title: Correlation ID Example version: '1.0.0' diff --git a/examples/gitter-streaming.yml b/examples/gitter-streaming.yml index 2305245d..1d53a01b 100644 --- a/examples/gitter-streaming.yml +++ b/examples/gitter-streaming.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' id: 'tag:stream.gitter.im,2022:api' info: title: Gitter Streaming API diff --git a/examples/mercure.yml b/examples/mercure.yml index 32f2a4ad..388f4dbc 100644 --- a/examples/mercure.yml +++ b/examples/mercure.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' info: title: Mercure Hub Example version: '1.0.0' diff --git a/examples/not.yml b/examples/not.yml index 957add7d..0b4e2e71 100644 --- a/examples/not.yml +++ b/examples/not.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' info: title: Not example version: '1.0.0' diff --git a/examples/oneof.yml b/examples/oneof.yml index d0697f49..6bc4c92e 100644 --- a/examples/oneof.yml +++ b/examples/oneof.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' info: title: OneOf example version: '1.0.0' diff --git a/examples/operation-security.yml b/examples/operation-security.yml index 0ee3c26c..f853072b 100644 --- a/examples/operation-security.yml +++ b/examples/operation-security.yml @@ -1,4 +1,4 @@ -asyncapi: 2.4.0 +asyncapi: 2.5.0 info: title: Notifications version: 1.0.0 diff --git a/examples/rpc-client.yml b/examples/rpc-client.yml index 5cbf1116..68f5d801 100644 --- a/examples/rpc-client.yml +++ b/examples/rpc-client.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' id: 'urn:example:rpcclient' defaultContentType: application/json diff --git a/examples/rpc-server.yml b/examples/rpc-server.yml index e7103e52..de4896eb 100644 --- a/examples/rpc-server.yml +++ b/examples/rpc-server.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' id: 'urn:example:rpcserver' defaultContentType: application/json diff --git a/examples/simple.yml b/examples/simple.yml index cb852949..329d5073 100644 --- a/examples/simple.yml +++ b/examples/simple.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' info: title: Account Service version: 1.0.0 diff --git a/examples/slack-rtm.yml b/examples/slack-rtm.yml index b4bef83b..20234a2b 100644 --- a/examples/slack-rtm.yml +++ b/examples/slack-rtm.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' id: 'wss://wss-primary.slack.com/websocket' info: title: Slack Real Time Messaging API diff --git a/examples/social-media/backend/asyncapi.yaml b/examples/social-media/backend/asyncapi.yaml index cefc2f98..5f7cb94e 100644 --- a/examples/social-media/backend/asyncapi.yaml +++ b/examples/social-media/backend/asyncapi.yaml @@ -13,6 +13,13 @@ servers: bindings: mqtt: clientId: websocketServer + tags: + - name: "env:production" + description: "This environment is meant for production use case" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:public" + description: "This resource is public and available to everyone" channels: comment/liked: diff --git a/examples/social-media/comments-service/asyncapi.yaml b/examples/social-media/comments-service/asyncapi.yaml index 0c0bddfd..ce8f93a9 100644 --- a/examples/social-media/comments-service/asyncapi.yaml +++ b/examples/social-media/comments-service/asyncapi.yaml @@ -12,6 +12,13 @@ servers: bindings: mqtt: clientId: comment-service + tags: + - name: "env:production" + description: "This environment is meant for production use case" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:public" + description: "This resource is public and available to everyone" channels: comment/liked: diff --git a/examples/social-media/notification-service/asyncapi.yaml b/examples/social-media/notification-service/asyncapi.yaml index 9952c962..be78362c 100644 --- a/examples/social-media/notification-service/asyncapi.yaml +++ b/examples/social-media/notification-service/asyncapi.yaml @@ -11,6 +11,13 @@ servers: bindings: mqtt: clientId: notification-service + tags: + - name: "env:production" + description: "This environment is meant for production use case" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:public" + description: "This resource is public and available to everyone" channels: comment/liked: diff --git a/examples/social-media/public-api/asyncapi.yaml b/examples/social-media/public-api/asyncapi.yaml index 9e9ea1ef..0a7cdde7 100644 --- a/examples/social-media/public-api/asyncapi.yaml +++ b/examples/social-media/public-api/asyncapi.yaml @@ -12,6 +12,13 @@ servers: bindings: mqtt: clientId: public-api + tags: + - name: "env:production" + description: "This environment is meant for production use case" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:public" + description: "This resource is public and available to everyone" channels: comment/liked: diff --git a/examples/streetlights-kafka.yml b/examples/streetlights-kafka.yml index d08cf639..91611115 100644 --- a/examples/streetlights-kafka.yml +++ b/examples/streetlights-kafka.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' info: title: Streetlights Kafka API version: '1.0.0' @@ -21,12 +21,26 @@ servers: description: Test broker secured with scramSha256 security: - saslScram: [] + tags: + - name: "env:test-scram" + description: "This environment is meant for running internal tests through scramSha256" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:private" + description: "This resource is private and only available to certain users" mtls-connections: url: test.mykafkacluster.org:28092 protocol: kafka-secure description: Test broker secured with X509 security: - certs: [] + tags: + - name: "env:test-mtls" + description: "This environment is meant for running internal tests through mtls" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:private" + description: "This resource is private and only available to certain users" defaultContentType: application/json diff --git a/examples/streetlights-mqtt.yml b/examples/streetlights-mqtt.yml index 5a000bd0..b3721d87 100644 --- a/examples/streetlights-mqtt.yml +++ b/examples/streetlights-mqtt.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' info: title: Streetlights MQTT API version: '1.0.0' @@ -33,6 +33,13 @@ servers: - streetlights:off - streetlights:dim - openIdConnectWellKnown: [] + tags: + - name: "env:production" + description: "This environment is meant for production use case" + - name: "kind:remote" + description: "This server is a remote server. Not exposed by the application" + - name: "visibility:public" + description: "This resource is public and available to everyone" defaultContentType: application/json diff --git a/examples/streetlights-operation-security.yml b/examples/streetlights-operation-security.yml index d75d9a37..faf12276 100644 --- a/examples/streetlights-operation-security.yml +++ b/examples/streetlights-operation-security.yml @@ -1,4 +1,4 @@ -asyncapi: '2.4.0' +asyncapi: '2.5.0' info: title: Streetlights Kafka API version: '1.0.0' diff --git a/examples/websocket-gemini.yml b/examples/websocket-gemini.yml index b4fc46df..75af8d4d 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.4.0' +asyncapi: '2.5.0' # # Overal information for users of the application diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 56fdd068..a2799ffb 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.4.0 +#### Version 2.5.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). @@ -361,11 +361,12 @@ 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 `{`braces`}`. -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`, `solace`, `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`, `solace`, `stomp`, `stomps`, `ws`, `wss`, `mercure`, `googlepubsub`. 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. +variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's URL template. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers. bindings | [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -399,19 +400,37 @@ The following shows how multiple servers can be described, for example, at the A "url": "development.gigantic-server.com", "description": "Development server", "protocol": "amqp", - "protocolVersion": "0.9.1" + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:development", + "description": "This environment is meant for developers to run their own tests" + } + ] }, "staging": { "url": "staging.gigantic-server.com", "description": "Staging server", "protocol": "amqp", - "protocolVersion": "0.9.1" + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:staging", + "description": "This environment is a replica of the production environment" + } + ] }, "production": { "url": "api.gigantic-server.com", "description": "Production server", "protocol": "amqp", - "protocolVersion": "0.9.1" + "protocolVersion": "0.9.1", + "tags": [ + { + "name": "env:production", + "description": "This environment is the live environment available for final users" + } + ] } } } @@ -424,16 +443,25 @@ servers: description: Development server protocol: amqp protocolVersion: 0.9.1 + tags: + - name: "env:development" + description: "This environment is meant for developers to run their own tests" staging: url: staging.gigantic-server.com description: Staging server protocol: amqp protocolVersion: 0.9.1 + tags: + - name: "env:staging" + description: "This environment is a replica of the production environment" production: url: api.gigantic-server.com description: Production server protocol: amqp protocolVersion: 0.9.1 + tags: + - name: "env:production" + description: "This environment is the live environment available for final users" ``` The following shows how variables can be used for a server configuration: @@ -714,7 +742,7 @@ Field Name | Type | Description summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. traits | [[Operation Trait Object](#operationTraitObject) | [Reference Object](#referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. @@ -825,7 +853,7 @@ Field Name | Type | Description summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. @@ -980,6 +1008,7 @@ Field Name | Type | Description `redis` | [Redis Server Binding](https://github.com/asyncapi/bindings/blob/master/redis#server) | Protocol-specific information for a Redis server. `mercure` | [Mercure Server Binding](https://github.com/asyncapi/bindings/blob/master/mercure#server) | Protocol-specific information for a Mercure server. `ibmmq` | [IBM MQ Server Binding](https://github.com/asyncapi/bindings/blob/master/ibmmq#server-binding-object) | Protocol-specific information for an IBM MQ server. +`googlepubsub` | [Google Cloud Pub/Sub Server Binding](https://github.com/asyncapi/bindings/blob/master/googlepubsub#server) | Protocol-specific information for a Google Cloud Pub/Sub server. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1010,6 +1039,7 @@ Field Name | Type | Description `redis` | [Redis Channel Binding](https://github.com/asyncapi/bindings/blob/master/redis#channel) | Protocol-specific information for a Redis channel. `mercure` | [Mercure Channel Binding](https://github.com/asyncapi/bindings/blob/master/mercure#channel) | Protocol-specific information for a Mercure channel. `ibmmq` | [IBM MQ Channel Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#channel-binding-object) | Protocol-specific information for an IBM MQ channel. +`googlepubsub` | [Google Cloud Pub/Sub Channel Binding](https://github.com/asyncapi/bindings/tree/master/googlepubsub#channel) | Protocol-specific information for a Google Cloud Pub/Sub channel. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1039,6 +1069,8 @@ Field Name | Type | Description `stomp` | [STOMP Operation Binding](https://github.com/asyncapi/bindings/blob/master/stomp/README.md#operation) | Protocol-specific information for a STOMP operation. `redis` | [Redis Operation Binding](https://github.com/asyncapi/bindings/blob/master/redis#operation) | Protocol-specific information for a Redis operation. `mercure` | [Mercure Operation Binding](https://github.com/asyncapi/bindings/blob/master/mercure#operation) | Protocol-specific information for a Mercure operation. +`googlepubsub` | [Google Cloud Pub/Sub Operation Binding](https://github.com/asyncapi/bindings/blob/master/googlepubsub#operation) | Protocol-specific information for a Google Cloud Pub/Sub operation. +`ibmmq` | [IBM MQ Operation Binding](https://github.com/asyncapi/bindings/blob/master/ibmmq#operation-binding-object) | Protocol-specific information for an IBM MQ operation. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1070,6 +1102,7 @@ Field Name | Type | Description `redis` | [Redis Message Binding](https://github.com/asyncapi/bindings/blob/master/redis#message) | Protocol-specific information for a Redis message. `mercure` | [Mercure Message Binding](https://github.com/asyncapi/bindings/blob/master/mercure#message) | Protocol-specific information for a Mercure message. `ibmmq` | [IBM MQ Message Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#message-binding-object) | Protocol-specific information for an IBM MQ message. +`googlepubsub` | [Google Cloud Pub/Sub Message Binding](https://github.com/asyncapi/bindings/tree/master/googlepubsub#message) | Protocol-specific information for a Google Cloud Pub/Sub message. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1097,7 +1130,7 @@ Field Name | Type | Description title | `string` | A human-friendly title for the message. summary | `string` | A short summary of what the message is about. description | `string` | A verbose explanation of the message. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of messages. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of messages. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message. bindings | [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. examples | [[Message Example Object](#messageExampleObject)] | List of examples. @@ -1111,7 +1144,7 @@ The following table contains a set of values that every implementation MUST supp Name | Allowed values | Notes ---|:---:|--- -[AsyncAPI 2.4.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.4.0`, `application/vnd.aai.asyncapi+json;version=2.4.0`, `application/vnd.aai.asyncapi+yaml;version=2.4.0` | This is the default when a `schemaFormat` is not provided. +[AsyncAPI 2.5.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.5.0`, `application/vnd.aai.asyncapi+json;version=2.5.0`, `application/vnd.aai.asyncapi+yaml;version=2.5.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. @@ -1296,7 +1329,7 @@ Field Name | Type | Description title | `string` | A human-friendly title for the message. summary | `string` | A short summary of what the message is about. description | `string` | A verbose explanation of the message. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of messages. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of messages. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message. bindings | [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. examples | [[Message Example Object](#messageExampleObject)] | List of examples.