From cf91499c006f4927e2b2e955cd04da676c55472b Mon Sep 17 00:00:00 2001 From: derberg Date: Tue, 4 Apr 2023 15:19:05 +0200 Subject: [PATCH 1/2] fix: revert changes to spec that were wrongly applied --- .../v3.0.0-next-major-spec.10.md | 904 ++++++++++-------- 1 file changed, 484 insertions(+), 420 deletions(-) diff --git a/pages/docs/reference/specification/v3.0.0-next-major-spec.10.md b/pages/docs/reference/specification/v3.0.0-next-major-spec.10.md index c0975b639874..dd6c6adc9054 100644 --- a/pages/docs/reference/specification/v3.0.0-next-major-spec.10.md +++ b/pages/docs/reference/specification/v3.0.0-next-major-spec.10.md @@ -1,10 +1,14 @@ +# ATTENTION: Work in progress + +This version is not yet ready to be used. We're currently working on it. If you want to join the effort and participate in the development of the next major version of AsyncAPI, head over to [GitHub Issue that we use for tracking 3.0 development progress](https://github.com/asyncapi/spec/issues/691). + # AsyncAPI Specification #### Disclaimer 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.6.0 +#### Version 3.0.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). @@ -12,49 +16,79 @@ The AsyncAPI Specification is licensed under [The Apache License, Version 2.0](h ## Introduction -The AsyncAPI Specification is a project used to describe and document message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). +The AsyncAPI Specification is a project used to describe message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). -The AsyncAPI Specification defines a set of files required to describe such an API. -These files can then be used to create utilities, such as documentation, integration and/or testing tools. +The AsyncAPI Specification defines a set of files required to describe the API of an [application](#definitionsApplication). +These files can be used to create utilities, such as documentation, code, integration, or testing tools. -The file(s) MUST describe the operations an [application](#definitionsApplication) accepts. For instance, consider the following AsyncAPI definition snippet: +The file(s) MUST describe the operations an [application](#definitionsApplication) performs. For instance, consider the following AsyncAPI definition snippet: ```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignUp" +channels: + userSignedUp: + # ...(redacted for brevity) +operations: + onUserSignedUp: + action: receive + channel: + $ref: "#/channels/userSignedUp" ``` -It means that the [application](#definitionsApplication) allows [consumers](#definitionsConsumer) to subscribe to the `user/signedup` [channel](#definitionsChannel) to receive userSignUp [messages](#definitionsMessage) produced by the application. +It means that the [application](#definitionsApplication) will subscribe to the `userSignedUp` [channel](#definitionsChannel) to receive messages. **The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol. +It's NOT RECOMMENDED to derive a [consumer](#definitionsConsumer) AsyncAPI document from a [producer](#definitionsProducer) one or vice versa. There are no guarantees that the channel used by an application to receive messages will be the same channel where another application is sending them. Also, certain fields in the document like `summary`, `description`, and the id of the operation might stop making sense. For instance, given the following consumer snippet: + +```yaml +operations: + onUserSignedUp: + summary: On user signed up. + description: Event received when a user signed up on the product. + action: receive + channel: + $ref: "#/channels/userSignedUp" +``` + +We can't automatically assume that an _opposite_ application exists by simply replacing `receive` with `send`: + +```yaml +operations: + onUserSignedUp: # <-- This doesn't make sense now. Should be something like sendUserSignedUp. + summary: On user signed up. # <-- This doesn't make sense now. Should say something like "Sends a user signed up event". + description: Event received when a user signed up on the product. # <-- This doesn't make sense now. Should speak about sending an event, not receiving it. + action: send + channel: + $ref: "#/channels/userSignedUp" +``` + +Aside from the issues mentioned above, there may also be infrastructure configuration that is not represented here. For instance, a system may use a read-only channel for receiving messages, a different one for sending them, and an intermediary process that will forward messages from one channel to the other. + ## Definitions -#### Server +### Server A server MAY be a message broker that is capable of sending and/or receiving between a [producer](#definitionsProducer) and [consumer](#definitionsConsumer). A server MAY be a service with WebSocket API that enables message-driven communication between browser-to-server or server-to-server. -#### Application +### Application An application is any kind of computer program or a group of them. It MUST be a [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the [server](#definitionsServer) in order to connect and exchange [messages](#definitionsMessage). -#### Producer +### Producer A producer is a type of application, connected to a [server](#definitionsServer), that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the [server](#definitionsServer), protocol, and use-case pattern. -#### Consumer +### Consumer A consumer is a type of application, connected to a [server](#definitionsServer) via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. -#### Message +### Message A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MUST contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. -#### Channel +### Channel A channel is an addressable component, made available by the [server](#definitionsServer), for the organization of [messages](#definitionsMessage). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume messages from channels. [Servers](#definitionsServer) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#definitionsServer) 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, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket, Google Pub/Sub, Pulsar. +### 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, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket. -#### Bindings +### Bindings A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only. ## Specification @@ -90,6 +124,8 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA An AsyncAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Objects](#referenceObject) are used. +It is important to note that everything that is defined in an AsyncAPI document MUST be used by the implemented [Application](#definitionsApplication), with the exception of the [Components Object](#componentsObject). Everything that is defined inside the Components Object represents a resource that MAY or MAY NOT be used by the implemented [Application](#definitionsApplication). + By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. ### Absolute URLs @@ -112,11 +148,9 @@ 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. -components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. -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. - +channels | [Channels Object](#channelsObject) | The channels used by this [application](#definitionsApplication). +operations | [Operations Object](#operationsObject) | The operations this [application](#definitionsApplication) MUST implement. +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). This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -173,6 +207,8 @@ Field Name | Type | Description termsOfService | `string` | A URL to the Terms of Service for the API. This MUST be in the form of an absolute URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. +tags | [Tags Object](#tagsObject) | A list of tags for application API documentation control. Tags can be used for logical grouping of applications. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation of the exposed API. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -181,7 +217,8 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```json { "title": "AsyncAPI Sample App", - "description": "This is a sample server.", + "version": "1.0.1", + "description": "This is a sample app.", "termsOfService": "https://asyncapi.org/terms/", "contact": { "name": "API Support", @@ -192,13 +229,22 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, - "version": "1.0.1" + "externalDocs": { + "description": "Find more info here", + "url": "https://www.asyncapi.org" + }, + "tags": [ + { + "name": "e-commerce" + } + ] } ``` ```yaml title: AsyncAPI Sample App -description: This is a sample server. +version: 1.0.1 +description: This is a sample app. termsOfService: https://asyncapi.org/terms/ contact: name: API Support @@ -207,7 +253,11 @@ contact: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html -version: 1.0.1 +externalDocs: + description: Find more info here + url: https://www.asyncapi.org +tags: + - name: e-commerce ``` #### Contact Object @@ -281,21 +331,70 @@ Field Pattern | Type | Description ```json { + "development": { + "host": "localhost:5672", + "description": "Development AMQP broker.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:development", + "description": "This environment is meant for developers to run their own tests." + } + ] + }, + "staging": { + "host": "rabbitmq-staging.in.mycompany.com:5672", + "description": "RabbitMQ broker for the staging environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:staging", + "description": "This environment is a replica of the production environment." + } + ] + }, "production": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" + "host": "rabbitmq.in.mycompany.com:5672", + "description": "RabbitMQ broker for the production environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:production", + "description": "This environment is the live environment available for final users." + } + ] } } ``` ```yaml +development: + host: localhost:5672 + description: Development AMQP broker. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:development" + description: "This environment is meant for developers to run their own tests." +staging: + host: rabbitmq-staging.in.mycompany.com:5672 + description: RabbitMQ broker for the staging environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:staging" + description: "This environment is a replica of the production environment." production: - url: development.gigantic-server.com - description: Development server - protocol: kafka - protocolVersion: '1.0.0' + host: rabbitmq.in.mycompany.com:5672 + description: RabbitMQ broker for the production environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:production" + description: "This environment is the live environment available for final users." ``` @@ -307,162 +406,57 @@ 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`, `googlepubsub`, `pulsar`. +host | `string` | **REQUIRED**. The server host name. It MAY include the port. This field supports [Server Variables](#serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. +protocol | `string` | **REQUIRED**. The protocol this server supports for connection. 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) \| [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. +pathname | `string` | The path to a resource in the host. This field supports [Server Variables](#serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. +description | `string` | An optional string describing the server. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +title | `string` | A human-friendly title for the server. +summary | `string` | A short summary of the server. +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 `host` and `pathname` template. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | A declaration of which security schemes can be used with this server. The list of values includes alternative [security scheme objects](#securitySchemeObject) that can be used. Only one of the security scheme 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. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this server. 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). - ##### Server Object Example A single server would be described as: ```json { - "url": "development.gigantic-server.com", - "description": "Development server", + "host": "kafka.in.mycompany.com:9092", + "description": "Production Kafka broker.", "protocol": "kafka", - "protocolVersion": "1.0.0" + "protocolVersion": "3.2" } ``` ```yaml -url: development.gigantic-server.com -description: Development server +host: kafka.in.mycompany.com:9092 +description: Production Kafka broker. protocol: kafka -protocolVersion: '1.0.0' +protocolVersion: '3.2' ``` -The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): +An example of a server that has a `pathname`: ```json { - "servers": { - "development": { - "url": "development.gigantic-server.com", - "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" - } - ] - } - } + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/production", + "protocol": "amqp", + "description": "Production RabbitMQ broker (uses the `production` vhost)." } ``` ```yaml -servers: - development: - url: development.gigantic-server.com - 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: - -```json -{ - "servers": { - "production": { - "url": "{username}.gigantic-server.com:{port}/{basePath}", - "description": "The production API server", - "protocol": "secure-mqtt", - "variables": { - "username": { - "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" - }, - "port": { - "enum": [ - "8883", - "8884" - ], - "default": "8883" - }, - "basePath": { - "default": "v2" - } - } - } - } -} -``` - -```yaml -servers: - production: - url: '{username}.gigantic-server.com:{port}/{basePath}' - description: The production API server - protocol: secure-mqtt - variables: - username: - # note! no enum here means it is an open value - default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` - port: - enum: - - '8883' - - '8884' - default: '8883' - basePath: - # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` - default: v2 +host: rabbitmq.in.mycompany.com:5672 +pathname: /production +protocol: amqp +description: Production RabbitMQ broker (uses the `production` vhost). ``` - #### Server Variable Object An object representing a Server Variable for server URL template substitution. @@ -478,8 +472,38 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). +##### Server Variable Object Example +```json +{ + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/{env}", + "protocol": "amqp", + "description": "RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`.", + "variables": { + "env": { + "description": "Environment to connect to. It can be either `production` or `staging`.", + "enum": [ + "production", + "staging" + ] + } + } +} +``` +```yaml +host: 'rabbitmq.in.mycompany.com:5672' +pathname: '/{env}' +protocol: amqp +description: RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`. +variables: + env: + description: Environment to connect to. It can be either `production` or `staging`. + enum: + - production + - staging +``` #### Default Content Type @@ -507,23 +531,22 @@ 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) | 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": { + "userSignedUp": { + "address": "user.signedup", + "messages": { + "userSignedUp": { "$ref": "#/components/messages/userSignedUp" } } @@ -532,55 +555,62 @@ Field Pattern | Type | Description ``` ```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignedUp" +userSignedUp: + address: 'user.signedup' + 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 ---|:---:|--- -$ref | `string` | Allows for a referenced definition of this channel item. The referenced structure MUST be in the form of a [Channel Item Object](#channelItemObject). In case a Channel Item Object field appears both in the defined object and the referenced object, the behavior is *undefined*. Resolution is done as defined by the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03).

**Deprecated:** Usage of the `$ref` property has been deprecated. -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 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.** +title | `string` | A human-friendly title for the channel. +summary | `string` | A short summary of the channel. +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 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). +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this channel. +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. + 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}", + "title": "Users channel", + "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", @@ -588,112 +618,173 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "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}' +title: Users channel +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: + + + + +#### 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}`. + + + + + +#### 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 { - "subscribe": { - "message": { - "oneOf": [ - { "$ref": "#/components/messages/signup" }, - { "$ref": "#/components/messages/login" } - ] - } + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" } } ``` ```yaml -subscribe: - message: - oneOf: - - $ref: '#/components/messages/signup' - - $ref: '#/components/messages/login' +userSignedUp: + $ref: '#/components/messages/userSignedUp' +userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' ``` -Using explicit by-name references to the servers on which the channel is available: + +#### Operations Object + +Holds a dictionary with all the [operations](#operationObject) this application MUST implement. + +> If you're looking for a place to define operations that MAY or MAY NOT be implemented by the application, consider defining them in [`components/operations`](#componentsOperations). + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +{operationId} | [Operation Object](#channelObject) \| [Reference Object](#referenceObject) | The operation this application MUST implement. The field name (`operationId`) MUST be a string used to identify the operation in the document where it is defined, and its value is **case-sensitive**. Tools and libraries MAY use the `operationId` to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. + +##### Operations 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" - } + "onUserSignUp": { + "title": "User sign up", + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { "$ref": "#/components/operationTraits/kafka" } + ] } } ``` ```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 +onUserSignUp: + title: User sign up + summary: Action to sign a user up. + description: A longer description + channel: + $ref: '#/channels/userSignup' + action: send + tags: + - name: user + - name: signup + - name: register + bindings: + amqp: + ack: false + traits: + - $ref: '#/components/operationTraits/kafka' ``` - - - #### Operation Object -Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. - -For example, an operation might describe a chat application use case where a user sends a text message to a group. A publish operation describes messages that are received by the chat application, whereas a subscribe operation describes messages that are sent by the chat application. +Describes a specific operation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. +action | `"send"` | `"receive"` | **Required**. Use `send` when it's expected that the application will send a message to the given [`channel`](#operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#operationObjectChannel). +channel | [Reference Object](#referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +title | `string` | A human-friendly title for the operation. 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. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#serverObjectSecurity) also applies, it MUST also be satisfied. 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. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | 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. -message | [Message Object](#messageObject) | [Reference Object](#referenceObject) | Map["oneOf", [[Message Object](#messageObject) | [Reference Object](#referenceObject)]] | A definition of the message that will be published or received by this operation. Map containing a single `oneOf` key is allowed here to specify multiple messages. However, **a message MUST be valid only against one of the message objects.** +messages | [[Reference Object](#referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#messageObject) that can be processed by this operation. It MUST contain a subset of the messages defined in the [channel referenced in this operation](#operationObjectChannel). **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#messageObject) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain [Message Objects](#messageObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +reply | [Operation Reply Object](#operationReplyObject) | [Reference Object](#referenceObject) | The definition of the reply in a request-reply operation. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -701,9 +792,13 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```json { - "operationId": "registerUser", + "title": "User sign up", "summary": "Action to sign a user up.", "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", "security": [ { "petstore_auth": [ @@ -717,28 +812,6 @@ This object MAY be extended with [Specification Extensions](#specificationExtens { "name": "signup" }, { "name": "register" } ], - "message": { - "headers": { - "type": "object", - "properties": { - "applicationInstanceId": { - "description": "Unique identifier for a given instance of the publishing application", - "type": "string" - } - } - }, - "payload": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/userCreate" - }, - "signup": { - "$ref": "#/components/schemas/signup" - } - } - } - }, "bindings": { "amqp": { "ack": false @@ -746,14 +819,31 @@ This object MAY be extended with [Specification Extensions](#specificationExtens }, "traits": [ { "$ref": "#/components/operationTraits/kafka" } - ] + ], + "messages": [ + { "$ref": "/components/messages/userSignedUp" } + ], + "reply": { + "address": { + "location": "$message.header#/replyTo" + }, + "channel": { + "$ref": "#/channels/userSignupReply" + }, + "messages": [ + { "$ref": "/components/messages/userSignedUpReply" } + ], + } } ``` ```yaml -operationId: registerUser +title: User sign up summary: Action to sign a user up. description: A longer description +channel: + $ref: '#/channels/userSignup' +action: send security: - petstore_auth: - write:pets @@ -762,25 +852,20 @@ tags: - name: user - name: signup - name: register -message: - headers: - type: object - properties: - applicationInstanceId: - description: Unique identifier for a given instance of the publishing application - type: string - payload: - type: object - properties: - user: - $ref: "#/components/schemas/userCreate" - signup: - $ref: "#/components/schemas/signup" bindings: amqp: ack: false traits: - $ref: "#/components/operationTraits/kafka" +messages: + - $ref: '#/components/messages/userSignedUp' +reply: + address: + location: '$message.header#/replyTo' + channel: + $ref: '#/channels/userSignupReply' + messages: + - $ref: '#/components/messages/userSignedUpReply' ``` @@ -788,7 +873,7 @@ traits: #### Operation Trait Object -Describes a trait that MAY be applied to an [Operation Object](#operationObject). This object MAY contain any property from the [Operation Object](#operationObject), except `message` and `traits`. +Describes a trait that MAY be applied to an [Operation Object](#operationObject). This object MAY contain any property from the [Operation Object](#operationObject), except the `action`, `channel` and `traits` ones. If you're looking to apply traits to a message, see the [Message Trait Object](#messageTraitObject). @@ -796,12 +881,12 @@ If you're looking to apply traits to a message, see the [Message Trait Object](# Field Name | Type | Description ---|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. +title | `string` | A human-friendly title for the operation. 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. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#serverObjectSecurity) also applies, it MUST also be satisfied. 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. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | 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. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -827,6 +912,51 @@ bindings: +#### Operation Reply Object + +Describes the reply part that MAY be applied to an Operation Object. If an operation implements the request/reply pattern, the reply object represents the response message. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +address | [Operation Reply Address Object](#operationReplyAddressObject) | [Reference Object](#referenceObject) | Definition of the address that implementations MUST use for the reply. +channel | [Reference Object](#referenceObject) | A `$ref` pointer to the definition of the channel in which this operation is performed. When [address](#operationReplyAddressObject) is specified, the [`address` property](#channelObjectAddress) of the channel referenced by this property MUST be either `null` or not defined. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +messages | [[Reference Object](#referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#messageObject) that can be processed by this operation as reply. It MUST contain a subset of the messages defined in the [channel referenced in this operation reply](#operationObjectChannel). **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#messageObject) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain [Message Objects](#messageObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Operation Reply Address Object + +An object that specifies where an operation has to send the reply. + +For specifying and computing the location of a reply address, a [runtime expression](#runtimeExpression) is used. + + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- +description | `string` | An optional description of the address. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +location | `string` | **REQUIRED.** A [runtime expression](#runtimeExpression) that specifies the location of the reply address. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Examples + +```json +{ + "description": "Consumer inbox", + "location": "$message.header#/replyTo" +} +``` + +```yaml +description: Consumer Inbox +location: $message.header#/replyTo +``` + + #### Parameters Object Describes a map of parameters included in a channel name. @@ -956,7 +1086,6 @@ Field Name | Type | Description `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. -`pulsar` | [Pulsar Server Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#server-binding-object) | Protocol-specific information for a Pulsar server. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -988,7 +1117,6 @@ Field Name | Type | Description `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. -`pulsar` | [Pulsar Channel Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#channel-binding-object) | Protocol-specific information for a Pulsar channel. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1020,7 +1148,6 @@ Field Name | Type | Description `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. -`pulsar` | [Pulsar Operation Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#operation-binding-fields) | Protocol-specific information for a Pulsar operation. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1053,7 +1180,6 @@ Field Name | Type | Description `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. -`pulsar` | [Pulsar Message Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#message-binding-fields) | Protocol-specific information for a Pulsar message. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1082,7 +1208,7 @@ Field Name | Type | Description 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 logical grouping and categorization of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | 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. traits | [[Message Trait Object](#messageTraitObject) | [Reference Object](#referenceObject)] | A list of traits to apply to the message object. Traits MUST be merged into the message object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Message Object](#messageObject). @@ -1095,7 +1221,7 @@ The following table contains a set of values that every implementation MUST supp Name | Allowed values | Notes ---|:---:|--- -[AsyncAPI 2.6.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.6.0`, `application/vnd.aai.asyncapi+json;version=2.6.0`, `application/vnd.aai.asyncapi+yaml;version=2.6.0` | This is the default when a `schemaFormat` is not provided. +[AsyncAPI 3.0.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.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. @@ -1281,7 +1407,7 @@ Field Name | Type | Description 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 logical grouping and categorization of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | 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. @@ -1352,7 +1478,7 @@ payload: #### Tags Object -A Tags object is a list of Tag Objects. +A Tags object is a list of [Tag Objects](#tagObject). An [Tag Object](#tagObject) in a list can be referenced by [Reference Object](#referenceObject). #### Tag Object @@ -1363,7 +1489,7 @@ Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED.** The name of the tag. description | `string` | A short description for the tag. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this tag. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1414,6 +1540,7 @@ description: Find more info here url: https://example.com ``` + #### Reference Object A simple object to allow referencing other components in the specification, internally and externally. @@ -1452,12 +1579,17 @@ 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). - serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). - channels | Map[`string`, [Channel Item Object](#channelItemObject)] | 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). + operations | Map[`string`, [Operation Item Object](#operationObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Item Objects](#operationObject). 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). + serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). correlationIds | Map[`string`, [Correlation ID Object](#correlationIdObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Correlation ID Objects](#correlationIdObject). +replies | Map[`string`, [Operation Reply Object](#operationReplyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Reply Objects](#operationReplyObject). + replyAddresses | Map[`string`, [Operation Reply Address Object](#operationReplyAddressObject) | [Reference Object](#referenceObject)] | An object to hold reusable [Operation Reply Address Objects](#operationReplyAddressObject). + externalDocs | Map[`string`, [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [External Documentation Objects](#externalDocumentationObject). + tags | Map[`string`, [Tag Object](#tagObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Tag Objects](#tagObject). operationTraits | Map[`string`, [Operation Trait Object](#operationTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Trait Objects](#operationTraitObject). messageTraits | Map[`string`, [Message Trait Object](#messageTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Trait Objects](#messageTraitObject). serverBindings | Map[`string`, [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Bindings Objects](#serverBindingsObject). @@ -1512,10 +1644,10 @@ my.org.User }, "servers": { "development": { - "url": "{stage}.gigantic-server.com:{port}", - "description": "Development server", + "host": "{stage}.in.mycompany.com:{port}", + "description": "RabbitMQ broker", "protocol": "amqp", - "protocolVersion": "0.9.1", + "protocolVersion": "0-9-1", "variables": { "stage": { "$ref": "#/components/serverVariables/stage" @@ -1529,11 +1661,11 @@ my.org.User "serverVariables": { "stage": { "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" + "description": "This value is assigned by the service provider, in this example `mycompany.com`" }, "port": { - "enum": ["8883", "8884"], - "default": "8883" + "enum": ["5671", "5672"], + "default": "5672" } }, "channels": { @@ -1632,10 +1764,10 @@ components: type: string servers: development: - url: "{stage}.gigantic-server.com:{port}" - description: Development server + url: "{stage}.in.mycompany.com:{port}" + description: RabbitMQ broker protocol: amqp - protocolVersion: 0.9.1 + protocolVersion: 0-9-1 variables: stage: $ref: "#/components/serverVariables/stage" @@ -1644,10 +1776,10 @@ components: serverVariables: stage: default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` + description: This value is assigned by the service provider, in this example `mycompany.com` port: - enum: [8883, 8884] - default: 8883 + enum: [5671, 5672] + default: 5672 channels: user/signedup: subscribe: @@ -1755,7 +1887,7 @@ In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields Field Name | Type | Description ---|:---:|--- discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#schemaComposition) for more details. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this schema. deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1769,7 +1901,7 @@ While composition offers model extensibility, it does not imply a hierarchy betw To support polymorphism, AsyncAPI Specification adds the support of the `discriminator` field. When used, the `discriminator` will be the name of the property used to decide which schema definition is used to validate the structure of the model. As such, the `discriminator` field MUST be a required field. -There are two ways to define the value of a discriminator for an inheriting instance. +There are are two ways to define the value of a discriminator for an inheriting instance. - Use the schema's name. - Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. @@ -2188,6 +2320,7 @@ Field Name | Type | Applies To | Description bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of an absolute URL. +scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -2215,7 +2348,7 @@ type: userPassword ``` ```yaml -type: apiKey, +type: apiKey in: user ``` @@ -2297,12 +2430,15 @@ bearerFormat: JWT "flows": { "implicit": { "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { + "availableScopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } } - } + }, + "scopes": [ + "write:pets" + ] } ``` @@ -2311,9 +2447,11 @@ type: oauth2 flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog - scopes: + availableScopes: write:pets: modify pets in your account read:pets: read your pets +scopes: + - 'write:pets' ``` ###### SASL Sample @@ -2352,7 +2490,7 @@ Field Name | Type | Applies To | Description authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of an absolute URL. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. +availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -2360,98 +2498,24 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```JSON { - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - }, - "authorizationCode": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" } } ``` ```YAML -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your pets - authorizationCode: - authorizationUrl: https://example.com/api/oauth/dialog - tokenUrl: https://example.com/api/oauth/token - scopes: - write:pets: modify pets in your account - read:pets: read your pets +authorizationUrl: https://example.com/api/oauth/dialog +tokenUrl: https://example.com/api/oauth/token +availableScopes: + write:pets: modify pets in your account + read:pets: read your pets ``` -#### Security Requirement Object - -Lists the required security schemes to execute this operation. -The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). - -When a list of Security Requirement Objects is defined on a [Server object](#serverObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the connection. -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names. Provide scopes that are required to establish successful connection with the server. If scopes are not needed, the list can be empty. For other security scheme types, the array MUST be empty. - -##### Security Requirement Object Examples - -###### User/Password Security Requirement - -```json -{ - "user_pass": [] -} -``` - -```yaml -user_pass: [] -``` - -###### API Key Security Requirement - -```json -{ - "api_key": [] -} -``` - -```yaml -api_key: [] -``` - -###### OAuth2 Security Requirement - -```json -{ - "petstore_auth": [ - "write:pets", - "read:pets" - ] -} -``` - -```yaml -petstore_auth: -- write:pets -- read:pets -``` ### Correlation ID Object @@ -2544,4 +2608,4 @@ binary | `string` | `binary` | any sequence of octets boolean | `boolean` | | | date | `string` | `date` | As defined by `full-date` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6) dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6) -password | `string` | `password` | Used to hint UIs the input needs to be obscured. +password | `string` | `password` | Used to hint UIs the input needs to be obscured. \ No newline at end of file From cbc55337ddf1c2a259a4164b95459b8bf1cfc8c0 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Tue, 4 Apr 2023 18:45:49 -0700 Subject: [PATCH 2/2] Update pages/docs/reference/specification/v3.0.0-next-major-spec.10.md --- pages/docs/reference/specification/v3.0.0-next-major-spec.10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/reference/specification/v3.0.0-next-major-spec.10.md b/pages/docs/reference/specification/v3.0.0-next-major-spec.10.md index dd6c6adc9054..6dcc94fc48a4 100644 --- a/pages/docs/reference/specification/v3.0.0-next-major-spec.10.md +++ b/pages/docs/reference/specification/v3.0.0-next-major-spec.10.md @@ -1,6 +1,6 @@ # ATTENTION: Work in progress -This version is not yet ready to be used. We're currently working on it. If you want to join the effort and participate in the development of the next major version of AsyncAPI, head over to [GitHub Issue that we use for tracking 3.0 development progress](https://github.com/asyncapi/spec/issues/691). +This version is not yet ready to be used. We're currently working on it. If you want to join the effort and participate in the development of the next major version of AsyncAPI, head over to the [GitHub Issue that we use for tracking 3.0 development progress](https://github.com/asyncapi/spec/issues/691). # AsyncAPI Specification