AsyncAPI Specification

Attribution

Part of this content has been taken from the great work done by the folks at the OpenAPI Initiative.

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.

The AsyncAPI Specification is licensed under The Apache License, Version 2.0.

Introduction

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 fields that can be used in an AsyncAPI document to describe an application's API. The document may reference other files for additional details or shared fields, but it is typically a single, primary document that encapsulates the API description.

The AsyncAPI document SHOULD describe the operations an application performs. For instance, consider the following AsyncAPI definition snippet:

1channels:
2  userSignedUp:
3    # ...(redacted for brevity)
4operations:
5  onUserSignedUp:
6    action: receive
7    channel:
8      $ref: "#/channels/userSignedUp"

It means that the application will receive messages from the userSignedUp channel.

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 receiver AsyncAPI document from a sender 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 receiver snippet:

1operations:
2  onUserSignedUp:
3    summary: On user signed up.
4    description: Event received when a user signed up on the product.
5    action: receive
6    channel:
7      $ref: "#/channels/userSignedUp"

We can't automatically assume that an opposite application exists by simply replacing receive with send:

1operations:
2  onUserSignedUp: # <-- This doesn't make sense now. Should be something like sendUserSignedUp.
3    summary: On user signed up. # <-- This doesn't make sense now. Should say something like "Sends a user signed up event".
4    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.
5    action: send
6    channel:
7      $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

A server MAY be a message broker that is capable of sending and/or receiving between a sender and receiver. A server MAY be a service with WebSocket API that enables message-driven communication between browser-to-server or server-to-server.

Application

An application is any kind of computer program or a group of them. It MUST be a sender, a receiver, or both. An application MAY be a microservice, IoT device (sensor), mainframe process, message broker, etc. An application MAY be written in any number of different programming languages as long as they support the selected protocol. An application MUST also use a protocol supported by the server in order to connect and exchange messages.

Sender

A sender is a type of application, that is sending messages to channels. A sender MAY send to multiple channels depending on the server, protocol, and use-case pattern.

Receiver

A receiver is a type of application that is receiving messages from channels. A receiver MAY receive from multiple channels depending on the server, protocol, and the use-case pattern. A receiver MAY forward a received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and forwards them.

Message

A message is the mechanism by which information is exchanged via a channel between servers and applications. A message MAY contain a payload and MAY also contain headers. The headers MAY be subdivided into protocol-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

A channel is an addressable component, made available by the server, for the organization of messages. Sender applications send messages to channels and receiver applications receive messages from channels. Servers MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the server implementation, the channel MAY be included in the message via protocol-defined headers.

Protocol

A protocol is the mechanism (wireline protocol or API) by which messages are exchanged between the application and the channel. Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket, Google Pub/Sub, Pulsar.

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

Format

The files describing the message-driven API in accordance with the AsyncAPI Specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to represent a A2S (AsyncAPI Specification) file.

For example, if a field is said to have an array value, the JSON array representation will be used:

1{
2   "field" : [...]
3}

While the API is described using JSON it does not impose a JSON input/output to the API itself.

All field names in the specification are case sensitive.

The schema exposes two types of fields. Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name. Patterned fields can have multiple occurrences as long as each has a unique name.

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is recommended along with some additional constraints:

• Tags MUST be limited to those allowed by the JSON Schema ruleset
• Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset

File Structure

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 are used.

It is important to note that everything that is defined in an AsyncAPI document MUST be used by the implemented Application, with the exception of the Components Object. Everything that is defined inside the Components Object represents a resource that MAY or MAY NOT be used by the implemented Application.

By convention, the AsyncAPI Specification (A2S) file is named asyncapi.json or asyncapi.yaml.

Absolute URLs

Unless specified otherwise, all properties that are absolute URLs are defined by RFC3986, section 4.3.

Schema

AsyncAPI Object

This is the root document object for the API specification. It combines resource listing and API declaration together into one document.

Fixed Fields

This object MAY be extended with Specification Extensions.

AsyncAPI Version String

The version string signifies the version of the AsyncAPI Specification that the document complies to. The format for this string must be major.minor.patch. The patch may be suffixed by a hyphen and extra alphanumeric characters.

A major.minor shall be used to designate the AsyncAPI Specification version, and will be considered compatible with the AsyncAPI Specification specified by that major.minor version. The patch version will not be considered by tooling, making no distinction between 1.0.0 and 1.0.1.

In subsequent versions of the AsyncAPI Specification, care will be given such that increments of the minor version should not interfere with operations of tooling developed to a lower minor version. Thus a hypothetical 1.1.0 specification should be usable with tooling designed for 1.0.0.

Identifier

This field represents a unique universal identifier of the application the AsyncAPI document is defining. It must conform to the URI format, according to RFC3986.

It is RECOMMENDED to use a URN to globally and uniquely identify the application during long periods of time, even after it becomes unavailable or ceases to exist.

Examples

1{
2  "id": "urn:example:com:smartylighting:streetlights:server"
3}

id: 'urn:example:com:smartylighting:streetlights:server'

1{
2  "id": "https://github.com/smartylighting/streetlights-server"
3}

id: 'https://github.com/smartylighting/streetlights-server'

Info Object

The object provides metadata about the API. The metadata can be used by the clients if needed.

Fixed Fields

This object MAY be extended with Specification Extensions.

Info Object Example

1{
2  "title": "AsyncAPI Sample App",
3  "version": "1.0.1",
4  "description": "This is a sample app.",
5  "termsOfService": "https://asyncapi.org/terms/",
6  "contact": {
7    "name": "API Support",
8    "url": "https://www.asyncapi.org/support",
9    "email": "support@asyncapi.org"
10  },
11  "license": {
12    "name": "Apache 2.0",
13    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
14  },
15  "externalDocs": {
16    "description": "Find more info here",
17    "url": "https://www.asyncapi.org"
18  },
19  "tags": [
20    {
21      "name": "e-commerce"
22    }
23  ]
24}

1title: AsyncAPI Sample App
2version: 1.0.1
3description: This is a sample app.
4termsOfService: https://asyncapi.org/terms/
5contact:
6  name: API Support
7  url: https://www.asyncapi.org/support
8  email: support@asyncapi.org
9license:
10  name: Apache 2.0
11  url: https://www.apache.org/licenses/LICENSE-2.0.html
12externalDocs:
13  description: Find more info here
14  url: https://www.asyncapi.org
15tags:
16  - name: e-commerce

Contact Object

Contact information for the exposed API.

Fixed Fields

This object MAY be extended with Specification Extensions.

Contact Object Example

1{
2  "name": "API Support",
3  "url": "https://www.example.com/support",
4  "email": "support@example.com"
5}

1name: API Support
2url: https://www.example.com/support
3email: support@example.com

License Object

License information for the exposed API.

Fixed Fields

This object MAY be extended with Specification Extensions.

License Object Example

1{
2  "name": "Apache 2.0",
3  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
4}

1name: Apache 2.0
2url: https://www.apache.org/licenses/LICENSE-2.0.html

Servers Object

The Servers Object is a map of Server Objects.

Patterned Fields

Servers Object Example

1{
2  "development": {
3    "host": "localhost:5672",
4    "description": "Development AMQP broker.",
5    "protocol": "amqp",
6    "protocolVersion": "0-9-1",
7    "tags": [
8      { 
9        "name": "env:development",
10        "description": "This environment is meant for developers to run their own tests."
11      }
12    ]
13  },
14  "staging": {
15    "host": "rabbitmq-staging.in.mycompany.com:5672",
16    "description": "RabbitMQ broker for the staging environment.",
17    "protocol": "amqp",
18    "protocolVersion": "0-9-1",
19    "tags": [
20      { 
21        "name": "env:staging",
22        "description": "This environment is a replica of the production environment."
23      }
24    ]
25  },
26  "production": {
27    "host": "rabbitmq.in.mycompany.com:5672",
28    "description": "RabbitMQ broker for the production environment.",
29    "protocol": "amqp",
30    "protocolVersion": "0-9-1",
31    "tags": [
32      { 
33        "name": "env:production",
34        "description": "This environment is the live environment available for final users."
35      }
36    ]
37  }
38}

1development:
2  host: localhost:5672
3  description: Development AMQP broker.
4  protocol: amqp
5  protocolVersion: 0-9-1
6  tags:
7    - name: "env:development"
8      description: "This environment is meant for developers to run their own tests."
9staging:
10  host: rabbitmq-staging.in.mycompany.com:5672
11  description: RabbitMQ broker for the staging environment.
12  protocol: amqp
13  protocolVersion: 0-9-1
14  tags:
15    - name: "env:staging"
16      description: "This environment is a replica of the production environment."
17production:
18  host: rabbitmq.in.mycompany.com:5672
19  description: RabbitMQ broker for the production environment.
20  protocol: amqp
21  protocolVersion: 0-9-1
22  tags:
23    - name: "env:production"
24      description: "This environment is the live environment available for final users."

Server Object

An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools.

Fixed Fields

Server Object Example

A single server would be described as:

1{
2  "host": "kafka.in.mycompany.com:9092",
3  "description": "Production Kafka broker.",
4  "protocol": "kafka",
5  "protocolVersion": "3.2"
6}

1host: kafka.in.mycompany.com:9092
2description: Production Kafka broker.
3protocol: kafka
4protocolVersion: '3.2'

An example of a server that has a pathname:

1{
2  "host": "rabbitmq.in.mycompany.com:5672",
3  "pathname": "/production",
4  "protocol": "amqp",
5  "description": "Production RabbitMQ broker (uses the `production` vhost)."
6}

1host: rabbitmq.in.mycompany.com:5672
2pathname: /production
3protocol: amqp
4description: Production RabbitMQ broker (uses the `production` vhost).

Server Variable Object

An object representing a Server Variable for server URL template substitution.

Fixed Fields

This object MAY be extended with Specification Extensions.

Server Variable Object Example

1{
2  "host": "rabbitmq.in.mycompany.com:5672",
3  "pathname": "/{env}",
4  "protocol": "amqp",
5  "description": "RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`.",
6  "variables": {
7    "env": {
8      "description": "Environment to connect to. It can be either `production` or `staging`.",
9      "enum": [
10        "production",
11        "staging"
12      ]
13    }
14  }
15}

1host: 'rabbitmq.in.mycompany.com:5672'
2pathname: '/{env}'
3protocol: amqp
4description: RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`.
5variables:
6  env:
7    description: Environment to connect to. It can be either `production` or `staging`.
8    enum:
9      - production
10      - staging

Default Content Type

A string representing the default content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. application/json). This value MUST be used by schema parsers when the contentType property is omitted.

In case a message can't be encoded/decoded using this value, schema parsers MUST use their default content type.

Default Content Type Example

1{
2  "defaultContentType": "application/json"
3}

defaultContentType: application/json

Channels Object

An object containing all the Channel Object definitions the Application MUST use during runtime.

Patterned Fields

Channels Object Example

1{
2  "userSignedUp": {
3    "address": "user.signedup",
4    "messages": {
5      "userSignedUp": {
6        "$ref": "#/components/messages/userSignedUp"
7      }
8    }
9  }
10}

1userSignedUp:
2  address: 'user.signedup'
3  messages:
4    userSignedUp:
5      $ref: '#/components/messages/userSignedUp'

Channel Object

Describes a shared communication channel.

Fixed Fields

This object MAY be extended with Specification Extensions.

Channel Object Example

1{
2  "address": "users.{userId}",
3  "title": "Users channel",
4  "description": "This channel is used to exchange messages about user events.",
5  "messages": {
6    "userSignedUp": {
7      "$ref": "#/components/messages/userSignedUp"
8    },
9    "userCompletedOrder": {
10      "$ref": "#/components/messages/userCompletedOrder"
11    }
12  },
13  "parameters": {
14    "userId": {
15      "$ref": "#/components/parameters/userId"
16    }
17  },
18  "servers": [
19    { "$ref": "#/servers/rabbitmqInProd" },
20    { "$ref": "#/servers/rabbitmqInStaging" }
21  ],
22  "bindings": {
23    "amqp": {
24      "is": "queue",
25      "queue": {
26        "exclusive": true
27      }
28    }
29  },
30  "tags": [{
31    "name": "user",
32    "description": "User-related messages"
33  }],
34  "externalDocs": {
35    "description": "Find more info here",
36    "url": "https://example.com"
37  }
38}

1address: 'users.{userId}'
2title: Users channel
3description: This channel is used to exchange messages about user events.
4messages:
5  userSignedUp:
6    $ref: '#/components/messages/userSignedUp'
7  userCompletedOrder:
8    $ref: '#/components/messages/userCompletedOrder'
9parameters:
10  userId:
11    $ref: '#/components/parameters/userId'
12servers:
13  - $ref: '#/servers/rabbitmqInProd'
14  - $ref: '#/servers/rabbitmqInStaging'
15bindings:
16  amqp:
17    is: queue
18    queue:
19      exclusive: true
20tags:
21  - name: user
22    description: User-related messages
23externalDocs:
24  description: 'Find more info here'
25  url: 'https://example.com'

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

Messages Object Example

1{
2  "userSignedUp": {
3    "$ref": "#/components/messages/userSignedUp"
4  },
5  "userCompletedOrder": {
6    "$ref": "#/components/messages/userCompletedOrder"
7  }
8}

1userSignedUp:
2  $ref: '#/components/messages/userSignedUp'
3userCompletedOrder:
4  $ref: '#/components/messages/userCompletedOrder'

Operations Object

Holds a dictionary with all the operations 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.

Patterned Fields

Operations Object Example

1{
2  "onUserSignUp": {
3    "title": "User sign up",
4    "summary": "Action to sign a user up.",
5    "description": "A longer description",
6    "channel": {
7      "$ref": "#/channels/userSignup"
8    },
9    "action": "send",
10    "tags": [
11      { "name": "user" },
12      { "name": "signup" },
13      { "name": "register" }
14    ],
15    "bindings": {
16      "amqp": {
17        "ack": false
18      }
19    },
20    "traits": [
21      { "$ref": "#/components/operationTraits/kafka" }
22    ]
23  }
24}

1onUserSignUp:
2  title: User sign up
3  summary: Action to sign a user up.
4  description: A longer description
5  channel:
6    $ref: '#/channels/userSignup'
7  action: send
8  tags:
9    - name: user
10    - name: signup
11    - name: register
12  bindings:
13    amqp:
14      ack: false
15  traits:
16    - $ref: '#/components/operationTraits/kafka'

Operation Object

Describes a specific operation.

Fixed Fields

This object MAY be extended with Specification Extensions.

Operation Object Example

1{
2  "title": "User sign up",
3  "summary": "Action to sign a user up.",
4  "description": "A longer description",
5  "channel": {
6    "$ref": "#/channels/userSignup"
7  },
8  "action": "send",
9  "security": [
10    {
11     "petstore_auth": [
12       "write:pets",
13       "read:pets"
14     ]
15    }
16  ],
17  "tags": [
18    { "name": "user" },
19    { "name": "signup" },
20    { "name": "register" }
21  ],
22  "bindings": {
23    "amqp": {
24      "ack": false
25    }
26  },
27  "traits": [
28    { "$ref": "#/components/operationTraits/kafka" }
29  ],
30  "messages": [
31    { "$ref": "/components/messages/userSignedUp" }
32  ],
33  "reply": {
34    "address": {
35      "location": "$message.header#/replyTo"
36    },
37    "channel": {
38      "$ref": "#/channels/userSignupReply"
39    },
40    "messages": [
41      { "$ref": "/components/messages/userSignedUpReply" }
42    ],
43  }
44}

1title: User sign up
2summary: Action to sign a user up.
3description: A longer description
4channel:
5  $ref: '#/channels/userSignup'
6action: send
7security:
8  - petstore_auth:
9    - write:pets
10    - read:pets
11tags:
12  - name: user
13  - name: signup
14  - name: register
15bindings:
16  amqp:
17    ack: false
18traits:
19  - $ref: "#/components/operationTraits/kafka"
20messages:
21  - $ref: '#/components/messages/userSignedUp'
22reply:
23  address:
24    location: '$message.header#/replyTo'
25  channel:
26    $ref: '#/channels/userSignupReply'
27  messages:
28    - $ref: '#/components/messages/userSignedUpReply'

Operation Trait Object

Describes a trait that MAY be applied to an Operation Object. This object MAY contain any property from the Operation Object, except the action, channel, messages and traits ones.

If you're looking to apply traits to a message, see the Message Trait Object.

Fixed Fields

This object MAY be extended with Specification Extensions.

Operation Trait Object Example

1{
2  "bindings": {
3    "amqp": {
4      "ack": false
5    }
6  }
7}

1bindings:
2  amqp:
3    ack: false

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

This object MAY be extended with Specification Extensions.

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 is used.

Fixed Fields

This object MAY be extended with Specification Extensions.

Examples

1{
2  "description": "Consumer inbox",
3  "location": "$message.header#/replyTo"
4}

1description: Consumer Inbox
2location: $message.header#/replyTo

Parameters Object

Describes a map of parameters included in a channel address.

This map MUST contain all the parameters used in the parent channel address.

Patterned Fields

Parameters Object Example

1{
2  "address": "user/{userId}/signedup",
3  "parameters": {
4    "userId": {
5      "description": "Id of the user."
6    }
7  }
8}

1address: user/{userId}/signedup
2parameters:
3  userId:
4    description: Id of the user.

Parameter Object

Describes a parameter included in a channel address.

Fixed Fields

This object MAY be extended with Specification Extensions.

Parameter Object Example

1{
2  "address": "user/{userId}/signedup",
3  "parameters": {
4    "userId": {
5      "description": "Id of the user.",
6      "location": "$message.payload#/user/id"
7    }
8  }
9}

1address: user/{userId}/signedup
2parameters:
3  userId:
4    description: Id of the user.
5    location: $message.payload#/user/id

Server Bindings Object

Map describing protocol-specific definitions for a server.

Fixed Fields

This object MAY be extended with Specification Extensions.

Channel Bindings Object

Map describing protocol-specific definitions for a channel.

Fixed Fields

This object MAY be extended with Specification Extensions.

Operation Bindings Object

Map describing protocol-specific definitions for an operation.

Fixed Fields

This object MAY be extended with Specification Extensions.

Message Bindings Object

Map describing protocol-specific definitions for a message.

Fixed Fields

This object MAY be extended with Specification Extensions.

Message Object

Describes a message received on a given channel and operation.

Fixed Fields

This object MAY be extended with Specification Extensions.

Message Object Example

1{
2  "name": "UserSignup",
3  "title": "User signup",
4  "summary": "Action to sign a user up.",
5  "description": "A longer description",
6  "contentType": "application/json",
7  "tags": [
8    { "name": "user" },
9    { "name": "signup" },
10    { "name": "register" }
11  ],
12  "headers": {
13    "type": "object",
14    "properties": {
15      "correlationId": {
16        "description": "Correlation ID set by application",
17        "type": "string"
18      },
19      "applicationInstanceId": {
20        "description": "Unique identifier for a given instance of the publishing application",
21        "type": "string"
22      }
23    }
24  },
25  "payload": {
26    "type": "object",
27    "properties": {
28      "user": {
29        "$ref": "#/components/schemas/userCreate"
30      },
31      "signup": {
32        "$ref": "#/components/schemas/signup"
33      }
34    }
35  },
36  "correlationId": {
37    "description": "Default Correlation ID",
38    "location": "$message.header#/correlationId"
39  },
40  "traits": [
41    { "$ref": "#/components/messageTraits/commonHeaders" }
42  ],
43  "examples": [
44    {
45      "name": "SimpleSignup",
46      "summary": "A simple UserSignup example message",
47      "headers": {
48        "correlationId": "my-correlation-id",
49        "applicationInstanceId": "myInstanceId"
50      },
51      "payload": {
52        "user": {
53          "someUserKey": "someUserValue"
54        },
55        "signup": {
56          "someSignupKey": "someSignupValue"
57        }
58      }
59    }
60  ]
61}

1name: UserSignup
2title: User signup
3summary: Action to sign a user up.
4description: A longer description
5contentType: application/json
6tags:
7  - name: user
8  - name: signup
9  - name: register
10headers:
11  type: object
12  properties:
13    correlationId:
14      description: Correlation ID set by application
15      type: string
16    applicationInstanceId:
17      description: Unique identifier for a given instance of the publishing application
18      type: string
19payload:
20  type: object
21  properties:
22    user:
23      $ref: "#/components/schemas/userCreate"
24    signup:
25      $ref: "#/components/schemas/signup"
26correlationId:
27  description: Default Correlation ID
28  location: $message.header#/correlationId
29traits:
30  - $ref: "#/components/messageTraits/commonHeaders"
31examples:
32  - name: SimpleSignup
33    summary: A simple UserSignup example message
34    headers:
35      correlationId: my-correlation-id
36      applicationInstanceId: myInstanceId
37    payload:
38      user:
39        someUserKey: someUserValue
40      signup:
41        someSignupKey: someSignupValue

Example using Avro to define the payload:

1{
2  "name": "UserSignup",
3  "title": "User signup",
4  "summary": "Action to sign a user up.",
5  "description": "A longer description",
6  "tags": [
7    { "name": "user" },
8    { "name": "signup" },
9    { "name": "register" }
10  ],
11  "payload": {
12    "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
13    "schema": {
14      "$ref": "path/to/user-create.avsc#/UserCreate"
15    }
16  }
17}

1name: UserSignup
2title: User signup
3summary: Action to sign a user up.
4description: A longer description
5tags:
6  - name: user
7  - name: signup
8  - name: register
9payload:
10  schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0'
11  schema:
12    $ref: 'path/to/user-create.avsc/#UserCreate'

Message Trait Object

Describes a trait that MAY be applied to a Message Object. This object MAY contain any property from the Message Object, except payload and traits.

If you're looking to apply traits to an operation, see the Operation Trait Object.

Fixed Fields

This object MAY be extended with Specification Extensions.

Message Trait Object Example

1{
2  "contentType": "application/json"
3}

contentType: application/json

Message Example Object

Message Example Object represents an example of a Message Object and MUST contain either headers and/or payload fields.

Fixed Fields

This object MAY be extended with Specification Extensions.

Message Example Object Example

1{
2  "name": "SimpleSignup",
3  "summary": "A simple UserSignup example message",
4  "headers": {
5    "correlationId": "my-correlation-id",
6    "applicationInstanceId": "myInstanceId"
7  },
8  "payload": {
9    "user": {
10      "someUserKey": "someUserValue"
11    },
12    "signup": {
13      "someSignupKey": "someSignupValue"
14    }
15  }
16}

1name: SimpleSignup
2summary: A simple UserSignup example message
3headers:
4  correlationId: my-correlation-id
5  applicationInstanceId: myInstanceId
6payload:
7  user:
8    someUserKey: someUserValue
9  signup:
10    someSignupKey: someSignupValue

Tags Object

A Tags object is a list of Tag Objects. An Tag Object in a list can be referenced by Reference Object.

Tag Object

Allows adding meta data to a single tag.

Fixed Fields

This object MAY be extended with Specification Extensions.

Tag Object Example

1{
2 "name": "user",
3 "description": "User-related messages"
4}

1name: user
2description: User-related messages

External Documentation Object

Allows referencing an external resource for extended documentation.

Fixed Fields

This object MAY be extended with Specification Extensions.

External Documentation Object Example

1{
2  "description": "Find more info here",
3  "url": "https://example.com"
4}

1description: Find more info here
2url: https://example.com

Reference Object

A simple object to allow referencing other components in the specification, internally and externally.

The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules. A JSON Reference SHALL only be used to refer to a schema that is formatted in either JSON or YAML. In the case of a YAML-formatted Schema, the JSON Reference SHALL be applied to the JSON representation of that schema. The JSON representation SHALL be made by applying the conversion described here.

For this specification, reference resolution is done as defined by the JSON Reference specification and not by the JSON Schema specification.

Fixed Fields

This object cannot be extended with additional properties and any properties added SHALL be ignored.

Reference Object Example

1{
2  "$ref": "#/components/schemas/Pet"
3}

  $ref: '#/components/schemas/Pet'

Components Object

Holds a set of reusable objects for different aspects of the AsyncAPI specification. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

Fixed Fields

This object MAY be extended with Specification Extensions.

All the fixed fields declared above are objects that MUST use keys that match the regular expression: ^[a-zA-Z0-9\.\-_]+$.

Field Name Examples:

1User
2User_1
3User_Name
4user-name
5my.org.User

Components Object Example

1{
2  "components": {
3    "schemas": {
4      "Category": {
5        "type": "object",
6        "properties": {
7          "id": {
8            "type": "integer",
9            "format": "int64"
10          },
11          "name": {
12            "type": "string"
13          }
14        }
15      },
16      "Tag": {
17        "type": "object",
18        "properties": {
19          "id": {
20            "type": "integer",
21            "format": "int64"
22          },
23          "name": {
24            "type": "string"
25          }
26        }
27      },
28      "AvroExample": {
29        "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
30        "schema": {
31          "$ref": "path/to/user-create.avsc#/UserCreate"
32        }
33      }
34    },
35    "servers": {
36      "development": {
37        "host": "{stage}.in.mycompany.com:{port}",
38        "description": "RabbitMQ broker",
39        "protocol": "amqp",
40        "protocolVersion": "0-9-1",
41        "variables": {
42          "stage": {
43            "$ref": "#/components/serverVariables/stage"
44          },
45          "port": {
46            "$ref": "#/components/serverVariables/port"
47          }
48        }
49      }
50    },
51    "serverVariables": {
52      "stage": {
53        "default": "demo",
54        "description": "This value is assigned by the service provider, in this example `mycompany.com`"
55      },
56      "port": {
57        "enum": ["5671", "5672"],
58        "default": "5672"
59      }
60    },
61    "channels": {
62      "user/signedup": {
63        "subscribe": {
64          "message": {
65            "$ref": "#/components/messages/userSignUp"
66          }
67        }
68      }
69    },
70    "messages": {
71      "userSignUp": {
72        "summary": "Action to sign a user up.",
73        "description": "Multiline description of what this action does.\nHere you have another line.\n",
74        "tags": [
75          {
76            "name": "user"
77          },
78          {
79            "name": "signup"
80          }
81        ],
82        "headers": {
83          "type": "object",
84          "properties": {
85            "applicationInstanceId": {
86              "description": "Unique identifier for a given instance of the publishing application",
87              "type": "string"
88            }
89          }
90        },
91        "payload": {
92          "type": "object",
93          "properties": {
94            "user": {
95              "$ref": "#/components/schemas/userCreate"
96            },
97            "signup": {
98              "$ref": "#/components/schemas/signup"
99            }
100          }
101        }
102      }
103    },
104    "parameters": {
105      "userId": {
106        "description": "Id of the user."
107      }
108    },
109    "correlationIds": {
110      "default": {
111        "description": "Default Correlation ID",
112        "location": "$message.header#/correlationId"
113      }
114    },
115    "messageTraits": {
116      "commonHeaders": {
117        "headers": {
118          "type": "object",
119          "properties": {
120            "my-app-header": {
121              "type": "integer",
122              "minimum": 0,
123              "maximum": 100
124            }
125          }
126        }
127      }
128    }
129  }
130}

1components:
2  schemas:
3    Category:
4      type: object
5      properties:
6        id:
7          type: integer
8          format: int64
9        name:
10          type: string
11    Tag:
12      type: object
13      properties:
14        id:
15          type: integer
16          format: int64
17        name:
18          type: string
19    AvroExample:
20      schemaFormat: application/vnd.apache.avro+json;version=1.9.0
21      schema:
22        $ref: 'path/to/user-create.avsc/#UserCreate'
23  servers:
24    development:
25      host: "{stage}.in.mycompany.com:{port}"
26      description: RabbitMQ broker
27      protocol: amqp
28      protocolVersion: 0-9-1
29      variables:
30        stage:
31          $ref: "#/components/serverVariables/stage"
32        port:
33          $ref: "#/components/serverVariables/port"
34  serverVariables:
35    stage:
36      default: demo
37      description: This value is assigned by the service provider, in this example `mycompany.com`
38    port:
39      enum: ["5671", "5672"]
40      default: "5672"
41  channels:
42    user/signedup:
43      subscribe:
44        message:
45          $ref: "#/components/messages/userSignUp"
46  messages:
47    userSignUp:
48      summary: Action to sign a user up.
49      description: |
50        Multiline description of what this action does.
51        Here you have another line.
52      tags:
53        - name: user
54        - name: signup
55      headers:
56        type: object
57        properties:
58          applicationInstanceId:
59            description: Unique identifier for a given instance of the publishing application
60            type: string
61      payload:
62        type: object
63        properties:
64          user:
65            $ref: "#/components/schemas/userCreate"
66          signup:
67            $ref: "#/components/schemas/signup"
68  parameters:
69    userId:
70      description: Id of the user.
71  correlationIds:
72    default:
73      description: Default Correlation ID
74      location: $message.header#/correlationId
75  messageTraits:
76    commonHeaders:
77      headers:
78        type: object
79        properties:
80          my-app-header:
81            type: integer
82            minimum: 0
83            maximum: 100

Multi Format Schema Object

The Multi Format Schema Object represents a schema definition. It differs from the Schema Object in that it supports multiple schema formats or languages (e.g., JSON Schema, Avro, etc.).

Fixed Fields

This object MAY be extended with Specification Extensions.

Schema formats table

The following table contains a set of values that every implementation MUST support.

The following table contains a set of values that every implementation is RECOMMENDED to support.

Multi Format Schema Object Examples

Multi Format Schema Object Example with Avro

1channels:
2  example:
3    messages:
4      myMessage:
5        payload:
6          schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
7          schema:
8            type: record
9            name: User
10            namespace: com.company
11            doc: User information
12            fields:
13              - name: displayName
14                type: string
15              - name: age
16                type: int

Schema Object

The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 07. The empty schema (which allows any instance to validate) MAY be represented by the boolean value true and a schema which allows no instance to validate MAY be represented by the boolean value false.

Further information about the properties can be found in JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. For other formats (e.g., Avro, RAML, etc) see Multi Format Schema Object.

Properties

The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such, any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to:

• title
• type
• required
• multipleOf
• maximum
• exclusiveMaximum
• minimum
• exclusiveMinimum
• maxLength
• minLength
• pattern (This string SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect)
• maxItems
• minItems
• uniqueItems
• maxProperties
• minProperties
• enum
• const
• examples
• if / then / else
• readOnly
• writeOnly
• properties
• patternProperties
• additionalProperties
• additionalItems
• items
• propertyNames
• contains
• allOf
• oneOf
• anyOf
• not