AsyncAPI Specification

Disclaimer

Part of this content has been taken from the great work done by the folks at the OpenAPI Initiative. Mainly because it's a great work and we want to keep as much compatibility as possible with the OpenAPI Specification.

Version 2.1.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 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 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 file(s) MUST describe the operations an application accepts. For instance, consider the following AsyncAPI definition snippet:

1user/signedup:
2  subscribe:
3    $ref: "#/components/messages/userSignUp"

It means that the application allows consumers to subscribe to the user/signedup channel to receive userSignUp messages produced by the application.

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.

Definitions

Application

An application is any kind of computer program or a group of them. It MUST be a producer, a consumer 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. An application MUST also use a protocol supported by the server in order to connect and exchange messages.

Producer

A producer is a type of application, connected to a server, that is creating messages and addressing them to channels. A producer MAY be publishing to multiple channels depending on the server, protocol, and use-case pattern.

Consumer

A consumer is a type of application, connected to a server via a supported protocol, that is consuming messages from channels. A consumer MAY be consuming from multiple channels depending on the server, protocol, and the use-case pattern.

Message

A message is the mechanism by which information is exchanged via a channel between servers and applications. A message MUST 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. Producer applications send messages to channels and consumer applications consume messages from channels. Servers MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the server implementation, the channel MAY be included in the message via protocol-defined headers.

Protocol

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

Bindings

A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only.

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

The A2S representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for $ref fields in the specification as follows from the JSON Schema definitions.

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

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 can 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:com:smartylighting:streetlights:server"
3}

id: 'urn: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 can be extended with Specification Extensions.

Info Object Example:

1{
2  "title": "AsyncAPI Sample App",
3  "description": "This is a sample server.",
4  "termsOfService": "https://asyncapi.org/terms/",
5  "contact": {
6    "name": "API Support",
7    "url": "https://www.asyncapi.org/support",
8    "email": "support@asyncapi.org"
9  },
10  "license": {
11    "name": "Apache 2.0",
12    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
13  },
14  "version": "1.0.1"
15}

1title: AsyncAPI Sample App
2description: This is a sample server.
3termsOfService: https://asyncapi.org/terms/
4contact:
5  name: API Support
6  url: https://www.asyncapi.org/support
7  email: support@asyncapi.org
8license:
9  name: Apache 2.0
10  url: https://www.apache.org/licenses/LICENSE-2.0.html
11version: 1.0.1

Contact Object

Contact information for the exposed API.

Fixed Fields

This object can 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 can 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  "production": {
3    "url": "development.gigantic-server.com",
4    "description": "Development server",
5    "protocol": "kafka",
6    "protocolVersion": "1.0.0"
7  }
8}

1production:
2  url: development.gigantic-server.com
3  description: Development server
4  protocol: kafka
5  protocolVersion: '1.0.0'

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

This object MAY be extended with Specification Extensions.

Server Object Example

A single server would be described as:

1{
2  "url": "development.gigantic-server.com",
3  "description": "Development server",
4  "protocol": "kafka",
5  "protocolVersion": "1.0.0"
6}

1url: development.gigantic-server.com
2description: Development server
3protocol: kafka
4protocolVersion: '1.0.0'

The following shows how multiple servers can be described, for example, at the AsyncAPI Object's servers:

1{
2  "servers": {
3    "development": {
4      "url": "development.gigantic-server.com",
5      "description": "Development server",
6      "protocol": "amqp",
7      "protocolVersion": "0.9.1"
8    },
9    "staging": {
10      "url": "staging.gigantic-server.com",
11      "description": "Staging server",
12      "protocol": "amqp",
13      "protocolVersion": "0.9.1"
14    },
15    "production": {
16      "url": "api.gigantic-server.com",
17      "description": "Production server",
18      "protocol": "amqp",
19      "protocolVersion": "0.9.1"
20    }
21  }
22}

1servers:
2  development:
3    url: development.gigantic-server.com
4    description: Development server
5    protocol: amqp
6    protocolVersion: 0.9.1
7  staging:
8    url: staging.gigantic-server.com
9    description: Staging server
10    protocol: amqp
11    protocolVersion: 0.9.1
12  production:
13    url: api.gigantic-server.com
14    description: Production server
15    protocol: amqp
16    protocolVersion: 0.9.1

The following shows how variables can be used for a server configuration:

1{
2  "servers": {
3    "production": {
4      "url": "{username}.gigantic-server.com:{port}/{basePath}",
5      "description": "The production API server",
6      "protocol": "secure-mqtt",
7      "variables": {
8        "username": {
9          "default": "demo",
10          "description": "This value is assigned by the service provider, in this example `gigantic-server.com`"
11        },
12        "port": {
13          "enum": [
14            "8883",
15            "8884"
16          ],
17          "default": "8883"
18        },
19        "basePath": {
20          "default": "v2"
21        }
22      }
23    }
24  }
25}

1servers:
2  production:
3    url: '{username}.gigantic-server.com:{port}/{basePath}'
4    description: The production API server
5    protocol: secure-mqtt
6    variables:
7      username:
8        # note! no enum here means it is an open value
9        default: demo
10        description: This value is assigned by the service provider, in this example `gigantic-server.com`
11      port:
12        enum:
13          - '8883'
14          - '8884'
15        default: '8883'
16      basePath:
17        # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
18        default: v2

Server Variable Object

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

Fixed Fields

This object MAY be extended with Specification Extensions.

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

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".

Patterned Fields

Channels Object Example

1{
2  "user/signedup": {
3    "subscribe": {
4      "$ref": "#/components/messages/userSignedUp"
5    }
6  }
7}

1user/signedup:
2  subscribe:
3    $ref: "#/components/messages/userSignedUp"

Channel Item Object

Describes the operations available on a single channel.

Fixed Fields

This object can be extended with Specification Extensions.

Channel Item Object Example

1{
2  "description": "This channel is used to exchange messages about users signing up",
3  "subscribe": {
4    "summary": "A user signed up.",
5    "message": {
6      "description": "A longer description of the message",
7      "payload": {
8        "type": "object",
9        "properties": {
10          "user": {
11            "$ref": "#/components/schemas/user"
12          },
13          "signup": {
14            "$ref": "#/components/schemas/signup"
15          }
16        }
17      }
18    }
19  },
20  "bindings": {
21    "amqp": {
22      "is": "queue",
23      "queue": {
24        "exclusive": true
25      }
26    }
27  }
28}

1description: This channel is used to exchange messages about users signing up
2subscribe:
3  summary: A user signed up.
4  message:
5    description: A longer description of the message
6    payload:
7      type: object
8      properties:
9        user:
10          $ref: "#/components/schemas/user"
11        signup:
12bindings:
13  amqp:
14    is: queue
15    queue:
16      exclusive: true

Using oneOf to specify multiple messages per operation:

1{
2  "subscribe": {
3    "message": {
4      "oneOf": [
5        { "$ref": "#/components/messages/signup" },
6        { "$ref": "#/components/messages/login" }
7      ]
8    }
9  }
10}

1subscribe:
2  message:
3    oneOf:
4      - $ref: '#/components/messages/signup'
5      - $ref: '#/components/messages/login'

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.

Fixed Fields

This object can be extended with Specification Extensions.

Operation Object Example

1{
2  "operationId": "registerUser",
3  "summary": "Action to sign a user up.",
4  "description": "A longer description",
5  "tags": [
6    { "name": "user" },
7    { "name": "signup" },
8    { "name": "register" }
9  ],
10  "message": {
11    "headers": {
12      "type": "object",
13      "properties": {
14        "applicationInstanceId": {
15          "description": "Unique identifier for a given instance of the publishing application",
16          "type": "string"
17        }
18      }
19    },
20    "payload": {
21      "type": "object",
22      "properties": {
23        "user": {
24          "$ref": "#/components/schemas/userCreate"
25        },
26        "signup": {
27          "$ref": "#/components/schemas/signup"
28        }
29      }
30    }
31  },
32  "bindings": {
33    "amqp": {
34      "ack": false
35    }
36  },
37  "traits": [
38    { "$ref": "#/components/operationTraits/kafka" }
39  ]
40}

1operationId: registerUser
2summary: Action to sign a user up.
3description: A longer description
4tags:
5  - name: user
6  - name: signup
7  - name: register
8message:
9  headers:
10    type: object
11    properties:
12      applicationInstanceId:
13        description: Unique identifier for a given instance of the publishing application
14        type: string
15  payload:
16    type: object
17    properties:
18      user:
19        $ref: "#/components/schemas/userCreate"
20      signup:
21        $ref: "#/components/schemas/signup"
22bindings:
23  amqp:
24    ack: false
25traits:
26  - $ref: "#/components/operationTraits/kafka"

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 message and traits.

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

Fixed Fields

This object can 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

Parameters Object

Describes a map of parameters included in a channel name.

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

Patterned Fields

Parameters Object Example

1{
2  "user/{userId}/signup": {
3    "parameters": {
4      "userId": {
5        "description": "Id of the user.",
6        "schema": {
7          "type": "string"
8        }
9      }
10    },
11    "subscribe": {
12      "$ref": "#/components/messages/userSignedUp"
13    }
14  }
15}

1user/{userId}/signup:
2  parameters:
3    userId:
4      description: Id of the user.
5      schema:
6        type: string
7  subscribe:
8    $ref: "#/components/messages/userSignedUp"

Parameter Object

Describes a parameter included in a channel name.

Fixed Fields

This object can be extended with Specification Extensions.

Parameter Object Example

1{
2  "user/{userId}/signup": {
3    "parameters": {
4      "userId": {
5        "description": "Id of the user.",
6        "schema": {
7          "type": "string"
8        },
9        "location": "$message.payload#/user/id"
10      }
11    },
12    "subscribe": {
13      "$ref": "#/components/messages/userSignedUp"
14    }
15  }
16}

1user/{userId}/signup:
2  parameters:
3    userId:
4      description: Id of the user.
5      schema:
6        type: string
7      location: $message.payload#/user/id
8  subscribe:
9    $ref: "#/components/messages/userSignedUp"

Server Bindings Object

Map describing protocol-specific definitions for a server.

Fixed Fields

This object can be extended with Specification Extensions.

Channel Bindings Object

Map describing protocol-specific definitions for a channel.

Fixed Fields

This object can be extended with Specification Extensions.

Operation Bindings Object

Map describing protocol-specific definitions for an operation.

Fixed Fields

This object can be extended with Specification Extensions.

Message Bindings Object

Map describing protocol-specific definitions for a message.

Fixed Fields

This object can be extended with Specification Extensions.

Message Object

Describes a message received on a given channel and operation.

Fixed Fields

This object can 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.

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  "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
12  "payload": {
13    "$ref": "path/to/user-create.avsc#/UserCreate"
14  }
15}

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
9schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0'
10payload:
11  $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 can be extended with Specification Extensions.

Message Trait Object Example

1{
2  "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0",
3  "contentType": "application/json"
4}

1schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0'
2contentType: application/json

Tags Object

A Tags object is a list of Tag Objects.

Tag Object

Allows adding meta data to a single tag.

Fixed Fields

This object can 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 can 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 can 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    },
29    "messages": {
30      "userSignUp": {
31        "summary": "Action to sign a user up.",
32        "description": "Multiline description of what this action does.\nHere you have another line.\n",
33        "tags": [
34          {
35            "name": "user"
36          },
37          {
38            "name": "signup"
39          }
40        ],
41        "headers": {
42          "type": "object",
43          "properties": {
44            "applicationInstanceId": {
45              "description": "Unique identifier for a given instance of the publishing application",
46              "type": "string"
47            }
48          }
49        },
50        "payload": {
51          "type": "object",
52          "properties": {
53            "user": {
54              "$ref": "#/components/schemas/userCreate"
55            },
56            "signup": {
57              "$ref": "#/components/schemas/signup"
58            }
59          }
60        }
61      }
62    },
63    "parameters": {
64      "userId": {
65        "description": "Id of the user.",
66        "schema": {
67          "type": "string"
68        }
69      }
70    },
71    "correlationIds": {
72      "default": {
73        "description": "Default Correlation ID",
74        "location": "$message.header#/correlationId"
75      }
76    },
77    "messageTraits": {
78      "commonHeaders": {
79        "headers": {
80          "type": "object",
81          "properties": {
82            "my-app-header": {
83              "type": "integer",
84              "minimum": 0,
85              "maximum": 100
86            }
87          }
88        }
89      }
90    }
91  }
92}

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  messages:
20    userSignUp:
21      summary: Action to sign a user up.
22      description: |
23        Multiline description of what this action does.
24        Here you have another line.
25      tags:
26        - name: user
27        - name: signup
28      headers:
29        type: object
30        properties:
31          applicationInstanceId:
32            description: Unique identifier for a given instance of the publishing application
33            type: string
34      payload:
35        type: object
36        properties:
37          user:
38            $ref: "#/components/schemas/userCreate"
39          signup:
40            $ref: "#/components/schemas/signup"
41  parameters:
42    userId:
43      description: Id of the user.
44      schema:
45        type: string
46  correlationIds:
47    default:
48      description: Default Correlation ID
49      location: $message.header#/correlationId
50  messageTraits:
51    commonHeaders:
52      headers:
53        type: object
54        properties:
55          my-app-header:
56            type: integer
57            minimum: 0
58            maximum: 100

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.

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

The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification.

• description - CommonMark syntax can be used for rich text representation.
• format - See Data Type Formats for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats.
• default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of type is string, then default can be "foo" but cannot be 1.

Alternatively, any time a Schema Object can be used, a Reference Object can be used in its place. This allows referencing definitions in place of defining them inline.

In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation:

Fixed Fields

This object can be extended with Specification Extensions.

Composition and Inheritance (Polymorphism)

The AsyncAPI Specification allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes in an array of object definitions that are validated independently but together compose a single object.

While composition offers model extensibility, it does not imply a hierarchy between the models. 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 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.

As such, inline schema definitions, which do not have a given id, cannot be used in polymorphism.

Schema Object Examples

Primitive Sample

1{
2  "type": "string",
3  "format": "email"
4}

1type: string
2format: email

Simple Model

1{
2  "type": "object",
3  "required": [
4    "name"
5  ],
6  "properties": {
7    "name": {
8      "type": "string"
9    },
10    "address": {
11      "$ref": "#/components/schemas/Address"
12    },
13    "age": {
14      "type": "integer",
15      "format": "int32",
16      "minimum": 0
17    }
18  }
19}

1type: object
2required:
3- name
4properties:
5  name:
6    type: string
7  address:
8    $ref: '#/components/schemas/Address'
9  age:
10    type: integer
11    format: int32
12    minimum: 0

Model with Map/Dictionary Properties

For a simple string to string mapping:

1{
2  "type": "object",
3  "additionalProperties": {
4    "type": "string"
5  }
6}

1type: object
2additionalProperties:
3  type: string

For a string to model mapping:

1{
2  "type": "object",
3  "additionalProperties": {
4    "$ref": "#/components/schemas/ComplexModel"
5  }
6}

1type: object
2additionalProperties:
3  $ref: '#/components/schemas/ComplexModel'

Model with Example

1{
2  "type": "object",
3  "properties": {
4    "id": {
5      "type": "integer",
6      "format": "int64"
7    },
8    "name": {
9      "type": "string"
10    }
11  },
12  "required": [
13    "name"
14  ],
15  "example": {
16    "name": "Puma",
17    "id": 1
18  }
19}

1type: object
2properties:
3  id:
4    type: integer
5    format: int64
6  name:
7    type: string
8required:
9- name
10example:
11  name: Puma
12  id: 1

Model with Boolean Schemas

1{
2  "type": "object",
3  "required": [
4    "anySchema"
5  ],
6  "properties": {
7    "anySchema": true,
8    "cannotBeDefined": false
9  }
10}

1type: object
2required:
3- anySchema
4properties:
5  anySchema: true
6  cannotBeDefined: false

Models with Composition

1{
2  "schemas": {
3    "ErrorModel": {
4      "type": "object",
5      "required": [
6        "message",
7        "code"
8      ],
9      "properties": {
10        "message": {
11          "type": "string"
12        },
13        "code": {
14          "type": "integer",
15          "minimum": 100,
16          "maximum": 600
17        }
18      }
19    },
20    "ExtendedErrorModel": {
21      "allOf": [
22        {
23          "$ref": "#/components/schemas/ErrorModel"
24        },
25        {
26          "type": "object",
27          "required": [
28            "rootCause"
29          ],
30          "properties": {
31            "rootCause": {
32              "type": "string"
33            }
34          }
35        }
36      ]
37    }
38  }
39}

1schemas:
2  ErrorModel:
3    type: object
4    required:
5    - message
6    - code
7    properties:
8      message:
9        type: string
10      code:
11        type: integer
12        minimum: 100
13        maximum: 600
14  ExtendedErrorModel:
15    allOf:
16    - $ref: '#/components/schemas/ErrorModel'
17    - type: object
18      required:
19      - rootCause
20      properties:
21        rootCause:
22          type: string

Models with Polymorphism Support

1{
2  "schemas": {
3    "Pet": {
4      "type": "object",
5      "discriminator": "petType",
6      "properties": {
7        "name": {
8          "type": "string"
9        },
10        "petType": {
11          "type": "string"
12        }
13      },
14      "required": [
15        "name",
16        "petType"
17      ]
18    },
19    "Cat": {
20      "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
21      "allOf": [
22        {
23          "$ref": "#/components/schemas/Pet"
24        },
25        {
26          "type": "object",
27          "properties": {
28            "huntingSkill": {
29              "type": "string",
30              "description": "The measured skill for hunting",
31              "enum": [
32                "clueless",
33                "lazy",
34                "adventurous",
35                "aggressive"
36              ]
37            }
38          },
39          "required": [
40            "huntingSkill"
41          ]
42        }
43      ]
44    },
45    "Dog": {
46      "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
47      "allOf": [
48        {
49          "$ref": "#/components/schemas/Pet"
50        },
51        {
52          "type": "object",
53          "properties": {
54            "packSize": {
55              "type": "integer",
56              "format": "int32",
57              "description": "the size of the pack the dog is from",
58              "minimum": 0
59            }
60          },
61          "required": [
62            "packSize"
63          ]
64        }
65      ]
66    },
67    "StickInsect": {
68      "description": "A representation of an Australian walking stick. Note that `StickBug` will be used as the discriminator value.",
69      "allOf": [
70        {
71          "$ref": "#/components/schemas/Pet"
72        },
73        {
74          "type": "object",
75          "properties": {
76            "petType": {
77              "const": "StickBug"
78            },
79            "color": {
80              "type": "string"
81            }
82          },
83          "required": [
84            "color"
85          ]
86        }
87      ]
88    }
89  }
90}

1schemas:
2  Pet:
3    type: object
4    discriminator: petType
5    properties:
6      name:
7        type: string
8      petType:
9        type: string
10    required:
11    - name
12    - petType
13  ## applies to instances with `petType: "Cat"`
14  ## because that is the schema name
15  Cat:
16    description: A representation of a cat
17    allOf:
18    - $ref: '#/components/schemas/Pet'
19    - type: object
20      properties:
21        huntingSkill:
22          type: string
23          description: The measured skill for hunting
24          enum:
25          - clueless
26          - lazy
27          - adventurous
28          - aggressive
29      required:
30      - huntingSkill
31  ## applies to instances with `petType: "Dog"`
32  ## because that is the schema name
33  Dog:
34    description: A representation of a dog
35    allOf:
36    - $ref: '#/components/schemas/Pet'
37    - type: object
38      properties:
39        packSize:
40          type: integer
41          format: int32
42          description: the size of the pack the dog is from
43          minimum: 0
44      required:
45      - packSize
46  ## applies to instances with `petType: "StickBug"`
47  ## because that is the required value of the discriminator field,
48  ## overriding the schema name
49  StickInsect:
50    description: A representation of an Australian walking stick
51    allOf:
52    - $ref: '#/components/schemas/Pet'
53    - type: object
54      properties:
55        petType:
56          const: StickBug
57        color:
58          type: string
59      required:
60      - color

Security Scheme Object

Defines a security scheme that can be used by the operations. Supported schemes are:

• User/Password.
• API key (either as user or as password).
• X.509 certificate.
• End-to-end encryption (either symmetric or asymmetric).
• HTTP authentication.
• HTTP API key.
• OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in RFC6749.
• OpenID Connect Discovery.
• SASL (Simple Authentication and Security Layer) as defined in RFC4422.

Fixed Fields