Skip to content

Latest commit

 

History

History
2453 lines (1995 loc) · 81.1 KB

asyncapi.md

File metadata and controls

2453 lines (1995 loc) · 81.1 KB
Raw

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.0.0-rc1

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 Asynchronous APIs.

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 will perform. For instance, consider the following AsyncAPI definition snippet:

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

Means that the application is a consumer because it subscribes to user/signedup channel and receives userSignUp messages.

Table of Contents

Definitions

Message Broker

A message broker is an intermediary component that translates a message from the messaging protocol of the sender to the messaging protocol of the receiver. The message broker mediates interactions between applications, minimizing the mutual awareness that applications should have of each other in order to be able to exchange messages, effectively providing decoupling. A message broker MUST support at least one protocol, thus enabling message exchanges between applications. Importantly, the message broker is a mechanism that enables asynchronous application patterns such as publish/subscribe, fire and forget, request/reply and queuing. Additionally, the message broker MAY provide additional features such as persistence, storage/replay, authentication/authorization, protocol transformation and message integrity.

Message

A message is the mechanism by which information is exchanged via a channel between message brokers and applications. A message MUST contain a payload and MAY also contain a header. The header 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 message broker, for the organization of messages. Producer applications send messages to channels and consumer applications consume messages from Channels. Message Brokers support many channel instances, allowing messages with different content to be addressed to different channels. Message Brokers MAY provide multiple channel types thus enabling different asynchronous application patterns such as topics, queues and exchanges. Depending on the message broker 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 hosted by the message broker. Example protocol include, but are not limited to, AMQP, HTTP, JMS, Kafka, MQTT, STOMP, WebSocket.

Application

An application is any kind of computer program connected to a message broker. 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 message broker in order to connect and exchange messages.

Producer

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

Consumer

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

Specification

Format

The files describing the Asynchronous 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:

{
   "field" : [...]
}

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
Field Name Type Description
asyncapi AsyncAPI Version String Required. Specifies the AsyncAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be major.minor.patch, where patch versions must be compatible with the existing major.minor tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding major.minor (1.0.*). Patch versions will correspond to patches of this document.
id Identifier Required. Identifier of the application the AsyncAPI document is defining.
info Info Object Required. Provides metadata about the API. The metadata can be used by the clients if needed.
servers [Server Object] An array of Server Objects, which provide connectivity information to a target server.
channels Channels Object Required The available channels and messages for the API.
components Components Object An element to hold various schemas for the specification.
tags [Tag Object] A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique.
externalDocs External Documentation Object Additional external documentation.

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
{
  "id": "urn:com:smartylighting:streetlights:server"
}
id: 'urn:com:smartylighting:streetlights:server'
{
  "id": "https://github.com/smartylighting/streetlights-server"
}
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
Field Name Type Description
title string Required. The title of the application.
version string Required Provides the version of the application API (not to be confused with the specification version).
description string A short description of the application. CommonMark syntax can be used for rich text representation.
termsOfService string A URL to the Terms of Service for the API. MUST be in the format of a URL.
contact Contact Object The contact information for the exposed API.
license License Object The license information for the exposed API.

This object can be extended with Specification Extensions.

Info Object Example:
{
  "title": "AsyncAPI Sample App",
  "description": "This is a sample server.",
  "termsOfService": "http://asyncapi.org/terms/",
  "contact": {
    "name": "API Support",
    "url": "http://www.asyncapi.org/support",
    "email": "support@asyncapi.org"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}
title: AsyncAPI Sample App
description: This is a sample server.
termsOfService: http://asyncapi.org/terms/
contact:
  name: API Support
  url: http://www.asyncapi.org/support
  email: support@asyncapi.org
license:
  name: Apache 2.0
  url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

Contact Object

Contact information for the exposed API.

Fixed Fields
Field Name Type Description
name string The identifying name of the contact person/organization.
url string The URL pointing to the contact information. MUST be in the format of a URL.
email string The email address of the contact person/organization. MUST be in the format of an email address.

This object can be extended with Specification Extensions.

Contact Object Example:
{
  "name": "API Support",
  "url": "http://www.example.com/support",
  "email": "support@example.com"
}
name: API Support
url: http://www.example.com/support
email: support@example.com

License Object

License information for the exposed API.

Fixed Fields
Field Name Type Description
name string Required. The license name used for the API.
url string A URL to the license used for the API. MUST be in the format of a URL.

This object can be extended with Specification Extensions.

License Object Example:
{
  "name": "Apache 2.0",
  "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html

Server Object

An object representing a Server.

Fixed Fields
Field Name Type Description
url string REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.
protocol string REQUIRED. The protocol this URL supports for connection. Supported protocol include, but are not limited to: amqp, amqps, http, https, jms, kafka, kafka-secure, mqtt, secure-mqtt, stomp, stomps, ws, wss.
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 MAY be used for rich text representation.
variables Map[string, Server Variable Object] A map between a variable name and its value. The value is used for substitution in the server's URL template.
baseChannel string A string describing the base channel. MUST be in the form of a RFC 3986 URI path. URI templates are not allowed here. Defaults to empty string.
security [Security Requirement Object] 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.

This object MAY be extended with Specification Extensions.

Server Object Example

A single server would be described as:

{
  "url": "development.gigantic-server.com",
  "description": "Development server",
  "protocol": "kafka",
  "protocolVersion": "1.0.0",
  "baseChannel": "company/events"
}
url: development.gigantic-server.com
description: Development server
protocol: kafka
protocolVersion: '1.0.0'
baseChannel: company/events

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

{
  "servers": [
    {
      "url": "development.gigantic-server.com",
      "description": "Development server",
      "protocol": "amqp",
      "protocolVersion": "0.9.1"
    },
    {
      "url": "staging.gigantic-server.com",
      "description": "Staging server",
      "protocol": "amqp",
      "protocolVersion": "0.9.1"
    },
    {
      "url": "api.gigantic-server.com",
      "description": "Production server",
      "protocol": "amqp",
      "protocolVersion": "0.9.1"
    }
  ]
}
servers:
- url: development.gigantic-server.com
  description: Development server
  protocol: amqp
  protocolVersion: 0.9.1
- url: staging.gigantic-server.com
  description: Staging server
  protocol: amqp
  protocolVersion: 0.9.1
- url: api.gigantic-server.com
  description: Production server
  protocol: amqp
  protocolVersion: 0.9.1

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

{
  "servers": [
    {
      "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"
        }
      }
    }
  ]
}
servers:
- 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

Server Variable Object

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

Fixed Fields
Field Name Type Description
enum [string] An enumeration of string values to be used if the substitution options are from a limited set.
default string The default value to use for substitution, and to send, if an alternate value is not supplied.
description string An optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
examples [string] An array of examples of the server variable.

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
{
  "defaultContentType": "application/json"
}
defaultContentType: application/json

Channels Object

Holds the relative paths to the individual channel and their operations. Channels starting with a slash (/) MUST be treated as absolute paths and therefore skipping the server's base channel. Otherwise, the final channel MUST be resolved using the server's base channel and the current path.

Patterned Fields
Field Pattern Type Description
{channel} Channel Item Object A relative path to an individual channel. The field name MUST be in the form of a RFC 6570 URI template.

This object can be extended with Specification Extensions.

Channels Object Example
{
  "user/signedup": {
    "subscribe": {
      "$ref": "#/components/messages/userSignedUp"
    }
  }
}
user/signedup:
  subscribe:
    $ref: "#/components/messages/userSignedUp"

Channel Item Object

Describes the operations available on a single channel.

Fixed Fields
Field Name Type Description
$ref string Allows for an external definition of this channel item. The referenced structure MUST be in the format of a Channel Item Object. If there are conflicts between the referenced definition and this Channel Item's definition, the behavior is undefined.
description string An optional description of this channel item. CommonMark syntax can be used for rich text representation.
subscribe Operation Object A definition of the SUBSCRIBE operation.
publish Operation Object A definition of the PUBLISH operation.
parameters [Parameter Object | Reference Object] A list 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).
protocolInfo Map[string, Protocol Info Object] A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel.

This object can be extended with Specification Extensions.

Channel Item Object Example
{
  "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"
          }
        }
      }
    }
  },
  "amqp-0-9-1": {
    "channelIsQueue": true,
    "queue": {
      "exclusive": true
    }
  }
}
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:
amqp-0-9-1:
  channelIsQueue: true
  queue:
    exclusive: true

Using oneOf to specify multiple messages per operation:

{
  "subscribe": {
    "message": {
      "oneOf": [
        { "$ref": "#/components/messages/signup" },
        { "$ref": "#/components/messages/login" }
      ]
    }
  }
}
subscribe:
  message:
    oneOf:
      - $ref: '#/components/messages/signup'
      - $ref: '#/components/messages/login'

Operation Object

Describes a publish or a subscribe 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.
summary string A short summary of what the operation is about.
description string A verbose explanation of the operation. CommonMark syntax can be used for rich text representation.
tags [Tag Object] A list of tags for API documentation control. Tags can be used for logical grouping of operations.
externalDocs External Documentation Object Additional external documentation for this operation.
protocolInfo Map[string, Protocol Info Object] A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.
traits [Operation Trait Object] | [[Operation Trait Object, Map]] A list of traits to apply to the operation object. The list MUST contain either a list of Operation Trait Objects or a list of tuples where the first element is an Operation Trait Object] and the second is a free-form object with the values of the variables a trait MAY use. All the variables of a trait MUST be provided. Traits MUST be merged into the operation object using the JSON Merge Patch algorithm in the same order they are defined here.
message Message Object A definition of the message that will be published or received on this channel. oneOf is allowed here to specify multiple messages, however, a message MUST be valid only against one of the referenced message objects.

This object can be extended with Specification Extensions.

Operation Object Example
{
  "operationId": "registerUser",
  "summary": "Action to sign a user up.",
  "description": "A longer description",
  "tags": [
    { "name": "user" },
    { "name": "signup" },
    { "name": "register" }
  ],
  "message": {
    "headers": {
      "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"
        }
      }
    }
  },
  "amqp-0-9-1": {
    "noAck": true
  },
  "traits": [
    { "$ref": "#/components/traits/kafka" },
    [
      { "$ref": "#/components/traits/docs" },
      { "headerId": "publish-1234" }
    ]
  ]
}
operationId: registerUser
summary: Action to sign a user up.
description: A longer description
tags:
  - name: user
  - name: signup
  - name: register
message:
  headers:
    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"
amqp-0-9-1:
  noAck: true
traits:
  - $ref: "#/components/traits/kafka"
  -
    - $ref: "#/components/traits/docs"
    - headerId: publish-1234

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.

All the string values of this object MUST support simple templating using the {{ and }} delimiters.

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.
summary string A short summary of what the operation is about.
description string A verbose explanation of the operation. CommonMark syntax can be used for rich text representation.
tags [Tag Object] A list of tags for API documentation control. Tags can be used for logical grouping of operations.
externalDocs External Documentation Object Additional external documentation for this operation.
protocolInfo Map[string, Protocol Info Object] A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.

This object can be extended with Specification Extensions.

Operation Trait Object Example
{
  "protocolInfo": {
    "amqp-0-9-1": {
      "noAck": true
    }
  }
}
protocolInfo:
  amqp-0-9-1:
    noAck: true
{
  "externalDocs": {
    "url": "https://mycompany.com/docs#{{headerId}}"
  }
}
externalDocs:
  url: "https://mycompany.com/docs#{{headerId}}"

Parameter Object

Describes a parameter included in a channel name.

Fixed Fields
Field Name Type Description
name string The name of the parameter.
description string A verbose explanation of the parameter. CommonMark syntax can be used for rich text representation.
schema Schema Object Definition of the parameter.

This object can be extended with Specification Extensions.

Parameter Object Example
{
  "user/{userId}/signup": {
    "parameters": [
      {
        "name": "userId",
        "description": "Id of the user.",
        "schema": {
          "type": "string"
        }
      }
    ],
    "subscribe": {
      "$ref": "#/components/messages/userSignedUp"
    }
  }
}
user/{userId}/signup:
  parameters:
    - name: userId
      description: Id of the user.
      schema:
        type: string
  subscribe:
    $ref: "#/components/messages/userSignedUp"

Protocol Info Object

Free-form key-value object describing protocol-specific definitions for channels, operations, and messages.

Patterned Fields
Field Pattern Type Description
{protocol} Map Protocol-specific information. This map is free-form and MUST not be validated by parsers.
Protocol Info Object Example
{
  "amqp-0-9-1": {
    "channelIsQueue": true,
    "queue": {
      "randomName": true,
      "exclusive": true
    }
  }
}
amqp-0-9-1:
  channelIsQueue: true
  queue:
    randomName: true
    exclusive: true

Message Object

Describes a message received on a given channel and operation.

Fixed Fields
Field Name Type Description
headers Map[string, Schema Object | Reference Object] Definition of the application headers. It does not define the protocol headers.
payload any Definition of the message payload. It can be of any type but defaults to Schema object.
correlationId Correlation ID Object | Reference Object Definition of the correlation ID used for message tracing or matching.
schemaFormat string A string containing the name of the schema format/language used to define the message payload. If omitted, implementations should parse the payload as a Schema object.
contentType string The content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. application/json). When omitted, the value MUST be the one specified on the defaultContentType field.
name string A machine-friendly name for the message.
title string A human-friendly title for the message.
summary string A short summary of what the message is about.
description string A verbose explanation of the message. CommonMark syntax can be used for rich text representation.
tags [Tag Object] A list of tags for API documentation control. Tags can be used for logical grouping of messages.
externalDocs External Documentation Object Additional external documentation for this message.
protocolInfo Map[string, Protocol Info Object] A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message.
examples [Map[string, any]] An array with examples of valid message objects.
traits [Message Trait Object] | [[Message Trait Object, Map]] A list of traits to apply to the message object. The list MUST contain either a list of Message Trait Objects or a list of tuples where the first element is a Message Trait Object] and the second is a free-form object with the values of the variables a trait may use. All the variables of a trait MUST be provided. Traits MUST be merged into the message object using the JSON Merge Patch algorithm in the same order they are defined here. The resulting object MUST be a valid Message Object.

This object can be extended with Specification Extensions.

Message Object Example
{
  "name": "UserSignup",
  "title": "User signup",
  "summary": "Action to sign a user up.",
  "description": "A longer description",
  "contentType": "application/json",
  "tags": [
    { "name": "user" },
    { "name": "signup" },
    { "name": "register" }
  ],
  "headers": {
    "correlationId": {
      "description": "Correlation ID set by application",
      "type": "string"
    },
    "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"
      }
    }
  },
  "correlationId": {
    "description": "Default Correlation ID",
    "location": "$message.header#/correlationId"
  },
  "amqp-0-9-1": {
    "properties": {
      "delivery_mode": 2
    }
  },
  "traits": [
    { "$ref": "#/components/traits/kafka" },
    [
      { "$ref": "#/components/traits/docs" },
      { "docId": "message-1234" }
    ]
  ]
}
name: UserSignup
title: User signup
summary: Action to sign a user up.
description: A longer description
contentType: application/json
tags:
  - name: user
  - name: signup
  - name: register
headers:
  correlationId:
    description: Correlation ID set by application
    type: string
  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"
correlationId:
  description: Default Correlation ID
  location: $message.header#/correlationId
amqp-0-9-1:
  properties:
    delivery_mode: 2
traits:
  - $ref: "#/components/traits/kafka"
  -
    - $ref: "#/components/traits/docs"
    - docId: message-1234

Example using Google's protobuf to define the payload:

{
  "name": "UserSignup",
  "title": "User signup",
  "summary": "Action to sign a user up.",
  "description": "A longer description",
  "tags": [
    { "name": "user" },
    { "name": "signup" },
    { "name": "register" }
  ],
  "schemaFormat": "application/x-protobuf",
  "payload": {
    "$ref": "path/to/user-create.proto#UserCreate"
  }
}
name: UserSignup
title: User signup
summary: Action to sign a user up.
description: A longer description
tags:
  - name: user
  - name: signup
  - name: register
schemaFormat: application/x-protobuf
payload:
  $ref: 'path/to/user-create.proto#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.

All the string values of this object MUST support simple templating using the {{ and }} delimiters.

Fixed Fields
Field Name Type Description
headers Map[string, Schema Object | Reference Object] Definition of the application headers. It does not define the protocol headers.
correlationId Correlation ID Object | Reference Object Definition of the correlation ID used for message tracing or matching.
schemaFormat string A string containing the name of the schema format/language used to define the message payload. If omitted, implementations should parse the payload as a Schema object.
contentType string The content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. application/json). When omitted, the value MUST be the one specified on the defaultContentType field.
name string A machine-friendly name for the message.
title string A human-friendly title for the message.
summary string A short summary of what the message is about.
description string A verbose explanation of the message. CommonMark syntax can be used for rich text representation.
tags [Tag Object] A list of tags for API documentation control. Tags can be used for logical grouping of messages.
externalDocs External Documentation Object Additional external documentation for this message.
protocolInfo Map[string, Protocol Info Object] A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message.
examples [Map[string, any]] An array with examples of valid message objects.

This object can be extended with Specification Extensions.

Message Trait Object Example
{
  "schemaFormat": "application/vnd.google.protobuf;version=3",
  "contentType": "application/json"
}
schemaFormat: 'application/vnd.google.protobuf;version=3'
contentType: application/json
{
  "externalDocs": {
    "url": "https://mycompany.com/docs#{{headerId}}"
  }
}
externalDocs:
  url: 'https://mycompany.com/docs#{{headerId}}'

Tag Object

Allows adding meta data to a single tag.

Fixed Fields
Field Name Type Description
name string Required. The name of the tag.
description string A short description for the tag. CommonMark syntax can be used for rich text representation.
externalDocs External Documentation Object Additional external documentation for this tag.

This object can be extended with Specification Extensions.

Tag Object Example
{
	"name": "user",
	"description": "User-related messages"
}
name: user
description: User-related messages

External Documentation Object

Allows referencing an external resource for extended documentation.

Fixed Fields
Field Name Type Description
description string A short description of the target documentation. CommonMark syntax can be used for rich text representation.
url string Required. The URL for the target documentation. Value MUST be in the format of a URL.

This object can be extended with Specification Extensions.

External Documentation Object Example
{
  "description": "Find more info here",
  "url": "https://example.com"
}
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.

The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules.

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

Fixed Fields
Field Name Type Description
$ref string Required. The reference string.

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

Reference Object Example
{
  "$ref": "#/components/schemas/Pet"
}
  $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
Field Name Type Description
schemas Map[string, Schema Object | Reference Object] An object to hold reusable Schema Objects.
messages Map[string, Message Object | Reference Object] An object to hold reusable Message Objects.
securitySchemes Map[string, Security Scheme Object | Reference Object] An object to hold reusable Security Scheme Objects.
parameters Map[string, Parameter Object | Reference Object] An object to hold reusable Parameter Objects.
correlationIds Map[string, Correlation ID Object] An object to hold reusable Correlation ID Objects.
traits Map[string, Operation Trait Object] | Message Trait Object] An object to hold reusable Operation Trait Objects and Message Trait Objects.

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:

User
User_1
User_Name
user-name
my.org.User
Components Object Example
"components": {
  "schemas": {
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "messages": {
    "userSignUp": {
      "summary": "Action to sign a user up.",
      "description": "Multiline description of what this action does.\nHere you have another line.\n",
      "tags": [
        {
          "name": "user"
        },
        {
          "name": "signup"
        }
      ],
      "headers": {
        "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"
          }
        }
      }
    }
  },
  "parameters": {
    "userId": {
      "name": "userId",
      "description": "Id of the user.",
      "schema": {
        "type": "string"
      }
    }
  },
  "correlationIds": {
    "default": {
      "description": "Default Correlation ID",
      "location": "$message.header#/correlationId"
    }
  },
  "traits": {
    "docs": {
      "externalDocs": {
        "url": "https://mycompany.com/docs#{{headerId}}"
      }
    }
  }
}
components:
  schemas:
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  messages:
    userSignUp:
      summary: Action to sign a user up.
      description: |
        Multiline description of what this action does.
        Here you have another line.
      tags:
        - name: user
        - name: signup
      headers:
        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"
  parameters:
    userId:
    - name: userId
      description: Id of the user.
      schema:
        type: string
  correlationIds:
    default:
      description: Default Correlation ID
      location: $message.header#/correlationId
  traits:
    docs:
      externalDocs:
        url: "https://mycompany.com/docs#{{headerId}}"

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 an extended subset of the JSON Schema Specification Wright Draft 00.

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 following properties are taken directly from the JSON Schema definition and follow the same specifications:

  • title
  • 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
  • required
  • enum

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

  • type - Value MUST be a string. Multiple types via an array are not supported.
  • allOf - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
  • oneOf - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
  • anyOf - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
  • not - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
  • items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
  • properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
  • additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
  • 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.

Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported.

Other than the JSON Schema subset fields, the following fields MAY be used for further schema documentation:

Fixed Fields
Field Name Type Description
nullable boolean Allows sending a null value for the defined schema. Default value is false.
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 for more details.
readOnly boolean Relevant only for Schema "properties" definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If property is marked as readOnly being true and is in the required list, the required will take effect on the response only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.
writeOnly boolean Relevant only for Schema "properties" definitions. Declares the property as "write only". This means that it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If property is marked as writeOnly being true and is in the required list, the required will take effect on the request only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.
xml XML Object This MAY be used only on properties schemas. It has no effect on root schemas. Adds Additional metadata to describe the XML representation format of this property.
externalDocs External Documentation Object Additional external documentation for this schema.
example Any A free-form property to include an example of an instance for this schema. To represent examples that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
examples [Any] An array of free-form properties to include examples of instances for this schema. To represent examples that cannot naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
deprecated boolean Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is false.

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.
XML Modeling

The xml property allows extra definitions when translating the JSON definition to XML. The XML Object contains additional information about the available options.

Schema Object Examples
Primitive Sample
{
  "type": "string",
  "format": "email"
}
type: string
format: email
Simple Model
{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "#/components/schemas/Address"
    },
    "age": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
    }
  }
}
type: object
required:
- name
properties:
  name:
    type: string
  address:
    $ref: '#/components/schemas/Address'
  age:
    type: integer
    format: int32
    minimum: 0
Model with Map/Dictionary Properties

For a simple string to string mapping:

{
  "type": "object",
  "additionalProperties": {
    "type": "string"
  }
}
type: object
additionalProperties:
  type: string

For a string to model mapping:

{
  "type": "object",
  "additionalProperties": {
    "$ref": "#/components/schemas/ComplexModel"
  }
}
type: object
additionalProperties:
  $ref: '#/components/schemas/ComplexModel'
Model with Example
{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "example": {
    "name": "Puma",
    "id": 1
  }
}
type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
- name
example:
  name: Puma
  id: 1
Models with Composition
{
  "schemas": {
    "ErrorModel": {
      "type": "object",
      "required": [
        "message",
        "code"
      ],
      "properties": {
        "message": {
          "type": "string"
        },
        "code": {
          "type": "integer",
          "minimum": 100,
          "maximum": 600
        }
      }
    },
    "ExtendedErrorModel": {
      "allOf": [
        {
          "$ref": "#/components/schemas/ErrorModel"
        },
        {
          "type": "object",
          "required": [
            "rootCause"
          ],
          "properties": {
            "rootCause": {
              "type": "string"
            }
          }
        }
      ]
    }
  }
}
schemas:
  ErrorModel:
    type: object
    required:
    - message
    - code
    properties:
      message:
        type: string
      code:
        type: integer
        minimum: 100
        maximum: 600
  ExtendedErrorModel:
    allOf:
    - $ref: '#/components/schemas/ErrorModel'
    - type: object
      required:
      - rootCause
      properties:
        rootCause:
          type: string
Models with Polymorphism Support
{
  "schemas": {
    "Pet": {
      "type": "object",
      "discriminator": "petType",
      "properties": {
        "name": {
          "type": "string"
        },
        "petType": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "petType"
      ]
    },
    "Cat": {
      "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
      "allOf": [
        {
          "$ref": "#/components/schemas/Pet"
        },
        {
          "type": "object",
          "properties": {
            "huntingSkill": {
              "type": "string",
              "description": "The measured skill for hunting",
              "enum": [
                "clueless",
                "lazy",
                "adventurous",
                "aggressive"
              ]
            }
          },
          "required": [
            "huntingSkill"
          ]
        }
      ]
    },
    "Dog": {
      "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
      "allOf": [
        {
          "$ref": "#/components/schemas/Pet"
        },
        {
          "type": "object",
          "properties": {
            "packSize": {
              "type": "integer",
              "format": "int32",
              "description": "the size of the pack the dog is from",
              "minimum": 0
            }
          },
          "required": [
            "packSize"
          ]
        }
      ]
    }
  }
}
schemas:
  Pet:
    type: object
    discriminator: petType
    properties:
      name:
        type: string
      petType:
        type: string
    required:
    - name
    - petType
  Cat:  ## "Cat" will be used as the discriminator value
    description: A representation of a cat
    allOf:
    - $ref: '#/components/schemas/Pet'
    - type: object
      properties:
        huntingSkill:
          type: string
          description: The measured skill for hunting
          enum:
          - clueless
          - lazy
          - adventurous
          - aggressive
      required:
      - huntingSkill
  Dog:  ## "Dog" will be used as the discriminator value
    description: A representation of a dog
    allOf:
    - $ref: '#/components/schemas/Pet'
    - type: object
      properties:
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          minimum: 0
      required:
      - packSize

XML Object

A metadata object that allows for more fine-tuned XML model definitions.

When using arrays, XML element names are not inferred (for singular/plural forms) and the name property SHOULD be used to add that information. See examples for expected behavior.

Fixed Fields
Field Name Type Description
name string Replaces the name of the element/attribute used for the described schema property. When defined within items, it will affect the name of the individual XML elements within the list. When defined alongside type being array (outside the items), it will affect the wrapping element and only if wrapped is true. If wrapped is false, it will be ignored.
namespace string The URL of the namespace definition. Value SHOULD be in the form of a URL.
prefix string The prefix to be used for the name.
attribute boolean Declares whether the property definition translates to an attribute instead of an element. Default value is false.
wrapped boolean MAY be used only for an array definition. Signifies whether the array is wrapped (for example, <books><book/><book/></books>) or unwrapped (<book/><book/>). Default value is false. The definition takes effect only when defined alongside type being array (outside the items).

This object can be extended with Specification Extensions.

XML Object Examples

The examples of the XML object definitions are included inside a property definition of a Schema Object with a sample of the XML representation of it.

No XML Element

Basic string property:

{
    "animals": {
        "type": "string"
    }
}
animals:
  type: string
<animals>...</animals>

Basic string array property (wrapped is false by default):

{
    "animals": {
        "type": "array",
        "items": {
            "type": "string"
        }
    }
}
animals:
  type: array
  items:
    type: string
<animals>...</animals>
<animals>...</animals>
<animals>...</animals>
XML Name Replacement
{
  "animals": {
    "type": "string",
    "xml": {
      "name": "animal"
    }
  }
}
animals:
  type: string
  xml:
    name: animal
<animal>...</animal>
XML Attribute, Prefix and Namespace

In this example, a full model definition is shown.

{
  "Person": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32",
        "xml": {
          "attribute": true
        }
      },
      "name": {
        "type": "string",
        "xml": {
          "namespace": "http://example.com/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}
Person:
  type: object
  properties:
    id:
      type: integer
      format: int32
      xml:
        attribute: true
    name:
      type: string
      xml:
        namespace: http://example.com/schema/sample
        prefix: sample
<Person id="123">
    <sample:name xmlns:sample="http://example.com/schema/sample">example</sample:name>
</Person>
XML Arrays

Changing the element names:

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    }
  }
}
animals:
  type: array
  items:
    type: string
    xml:
      name: animal
<animal>value</animal>
<animal>value</animal>

The external name property has no effect on the XML:

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens"
    }
  }
}
animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens
<animal>value</animal>
<animal>value</animal>

Even when the array is wrapped, if no name is explicitly defined, the same name will be used both internally and externally:

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "wrapped": true
    }
  }
}
animals:
  type: array
  items:
    type: string
  xml:
    wrapped: true
<animals>
  <animals>value</animals>
  <animals>value</animals>
</animals>

To overcome the above example, the following definition can be used:

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "wrapped": true
    }
  }
}
animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    wrapped: true
<animals>
  <animal>value</animal>
  <animal>value</animal>
</animals>

Affecting both internal and external names:

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}
animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens
    wrapped: true
<aliens>
  <animal>value</animal>
  <animal>value</animal>
</aliens>

If we change the external element but not the internal ones:

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}
animals:
  type: array
  items:
    type: string
  xml:
    name: aliens
    wrapped: true
<aliens>
  <aliens>value</aliens>
  <aliens>value</aliens>
</aliens>

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.
Fixed Fields
Field Name Type Applies To Description
type string Any REQUIRED. The type of the security scheme. Valid values are "userPassword", "apiKey", "X509", "symmetricEncryption", "asymmetricEncryption", "httpApiKey", "http".
description string Any A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
name string httpApiKey REQUIRED. The name of the header, query or cookie parameter to be used.
in string apiKey | httpApiKey REQUIRED. The location of the API key. Valid values are "user" and "password" for apiKey and "query", "header" or "cookie" for httpApiKey.
scheme string http REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.
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 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 a URL.

This object MAY be extended with Specification Extensions.

Security Scheme Object Example
User/Password Authentication Sample
{
  "type": "userPassword"
}
type: userPassword
API Key Authentication Sample
{
  "type": "apiKey",
  "in": "user"
}
type: apiKey,
in: user
X.509 Authentication Sample
{
  "type": "X509"
}
type: X509
End-to-end Encryption Authentication Sample
{
  "type": "symmetricEncryption"
}
type: symmetricEncryption
Basic Authentication Sample
{
  "type": "http",
  "scheme": "basic"
}
type: http
scheme: basic
API Key Sample
{
  "type": "httpApiKey",
  "name": "api_key",
  "in": "header"
}
type: httpApiKey
name: api_key
in: header
JWT Bearer Sample
{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT",
}
type: http
scheme: bearer
bearerFormat: JWT
Implicit OAuth2 Sample
{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}
type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

OAuth Flows Object

Allows configuration of the supported OAuth Flows.

Fixed Fields
Field Name Type Description
implicit OAuth Flow Object Configuration for the OAuth Implicit flow
password OAuth Flow Object Configuration for the OAuth Resource Owner Protected Credentials flow
clientCredentials OAuth Flow Object Configuration for the OAuth Client Credentials flow.
authorizationCode OAuth Flow Object Configuration for the OAuth Authorization Code flow.

This object MAY be extended with Specification Extensions.

OAuth Flow Object

Configuration details for a supported OAuth Flow

Fixed Fields
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 a URL.
tokenUrl string oauth2 ("password", "clientCredentials", "authorizationCode") REQUIRED. The token URL to be used for this flow. This MUST be in the form of a URL.
refreshUrl string oauth2 The URL to be used for obtaining refresh tokens. This MUST be in the form of a 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.

This object MAY be extended with Specification Extensions.

OAuth Flow Object Examples
{
  "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"
      }
    }
  }
}
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

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 under the Components Object.

When a list of Security Requirement Objects is defined on the AsyncAPI object, only one of Security Requirement Objects in the list needs to be satisfied to authorize the connection or operation.

Patterned Fields
Field Pattern Type Description
{name} [string] Each name MUST correspond to a security scheme which is declared in the Security Schemes under the Components Object. If the security scheme is of type "oauth2" or "openIdConnect", then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty.
Security Requirement Object Examples
User/Password Security Requirement
{
  "user_pass": []
}
user_pass: []
API Key Security Requirement
{
  "api_key": []
}
api_key: []
OAuth2 Security Requirement
{
  "petstore_auth": [
    "write:pets",
    "read:pets"
  ]
}
petstore_auth:
- write:pets
- read:pets

Correlation ID Object

An object that specifies an identifier at design time that can used for message tracing and correlation.

For specifying and computing the location of a Correlation ID, a runtime expression is used.

Fixed Fields
Field Name Type Description
description string A optional description of the identifier. CommonMark syntax can be used for rich text representation.
location {expression} REQUIRED. A runtime expression that specifies the location of the correlation ID.

This object can be extended with Specification Extensions.

Examples
{
  "description": "Default Correlation ID",
  "location": "$message.header#/correlationId"
}
description: Default Correlation ID
location: $message.header#/correlationId

Runtime Expression

A runtime expression allows values to be defined based on information that will be available within the message. This mechanism is used by Correlation ID Object.

The runtime expression is defined by the following ABNF syntax:

      expression = ( "$message" "." source )
      source = ( header-reference | payload-reference )
      header-reference = "header." ["#" fragment]
      payload-reference = "payload." ["#" fragment]
      fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901)

The table below provides examples of runtime expressions and examples of their use in a value:

Examples
Source Location Example expression Notes
Message Header Property $message.header#/MQMD/CorrelId Correlation ID is set using the CorrelId value from the MQMD header.
Message Payload Property $message.payload#/messageId Correlation ID is set using the messageId value from the message payload.

Runtime expressions preserve the type of the referenced value.

Specification Extensions

While the AsyncAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

The extensions properties are implemented as patterned fields that are always prefixed by "x-".

Field Pattern Type Description
^x-[\w\d\-\_]+$ Any Allows extensions to the AsyncAPI Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. Can have any valid JSON format value.

The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced).

Data Type Formats

Primitives have an optional modifier property: format. The AsyncAPI specification uses several known formats to more finely define the data type being used. However, the format property is an open string-valued property, and can have any value to support documentation needs. Formats such as "email", "uuid", etc., can be used even though they are not defined by this specification. Types that are not accompanied by a format property follow their definition from the JSON Schema. Tools that do not recognize a specific format MAY default back to the type alone, as if the format was not specified.

The formats defined by the AsyncAPI Specification are:

Common Name type format Comments
integer integer int32 signed 32 bits
long integer int64 signed 64 bits
float number float
double number double
string string
byte string byte base64 encoded characters
binary string binary any sequence of octets
boolean boolean
date string date As defined by full-date - RFC3339
dateTime string date-time As defined by date-time - RFC3339
password string password Used to hint UIs the input needs to be obscured.