Part of this content has been taken from the great work done by the folks at the Open API Initiative. Mainly because it's a great work and we want to keep as much compatibility as possible with the Open API Specification.
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.
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 AsyncAPI Specification is often used to describe the inter-process communication (IPC) in distributed systems built using a broker-centric architecture. In such cases, it's very easy to get confused with what the AsyncAPI files must describe. It's RECOMMENDED to create a single file describing the whole system instead of creating a file for each process. Otherwise, you will end up having lots of interdependent files.
The file(s) MUST describe the operations a new process can perform. For instance:
event.user.signup:
subscribe:
$ref: "#/components/messages/userSignUp"
It means processes can subscribe to event.user.signup topic. However, it does NOT mean every process must subscribe to this topic.
A message broker is a system in charge of message exchange. It MAY provide additional features, such as message queueing, storage or processing.
A message is a piece of information a process will send to a message broker. It MUST contain headers and payload.
A topic is a routing key used by the message broker to deliver messages to the subscribed processes. Depending on the protocol used, a message MAY include the topic in its headers.
A process is any kind of computer program connected to a message broker. It MUST be a producer, a consumer or both.
A producer is a process publishing messages to a message broker.
A consumer is a process subscribed to a message broker and consumes messages from it.
Topic templating refers to the usage of curly braces ({}) to mark a section of a topic as replaceable.
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:
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.
This is the root document object for the API specification. It combines resource listing and API declaration together into one document.
| 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. |
| info | Info Object | Required. Provides metadata about the API. The metadata can be used by the clients if needed. |
| baseTopic | BaseTopic String | The base topic to the API. |
| servers | Server Object | An array of Server Objects, which provide connectivity information to a target server. |
| topics | Topics Object | Required. The available topics and messages for the API. |
| components | Components Object | An element to hold various schemas for the specification. |
| security | [Security Requirement Object] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. |
| tags | [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.
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.
The object provides metadata about the API. The metadata can be used by the clients if needed.
| 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.
{
"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 information for the exposed API.
This object can be extended with Specification Extensions.
{
"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 information for the exposed API.
| 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.
{
"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
The base topic to the API. You MAY use this field to avoid repeating the beginning of the topics.
{
"baseTopic": "hitch.accounts"
}
baseTopic: hitch.accounts
An object representing a Server.
| 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}. |
| scheme | string | REQUIRED. The scheme this URL supports for connection. The value MUST be one of the following: amqp, amqps, mqtt, mqtts, ws, wss, stomp, stomps. |
| 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. |
This object MAY be extended with Specification Extensions.
A single server would be described as:
{
"url": "development.gigantic-server.com",
"description": "Development server",
"scheme": "mqtts"
}
url: development.gigantic-server.com
description: Development server
scheme: mqtts
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",
"scheme": "mqtts"
},
{
"url": "staging.gigantic-server.com",
"description": "Staging server",
"scheme": "mqtts"
},
{
"url": "api.gigantic-server.com",
"description": "Production server",
"scheme": "mqtts"
}
]
}
servers:
- url: development.gigantic-server.com
description: Development server
scheme: mqtts
- url: staging.gigantic-server.com
description: Staging server
scheme: mqtts
- url: api.gigantic-server.com
description: Production server
scheme: mqtts
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",
"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
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
An object representing a Server Variable for server URL template substitution.
| 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. |
At least one of the fields MUST be provided.
This object MAY be extended with Specification Extensions.
Holds the relative paths to the individual topic and their operations.
The topic is appended to the Base Topic in order to construct the full one.
| Field Pattern | Type | Description |
|---|---|---|
| ^[^.]{topic} | Topic Item Object | A relative path to an individual topic. The field name MUST NOT begin with a dot. Topic templating is allowed. |
This object can be extended with Specification Extensions.
{
"accounts.1.0.event.user.signup": {
"subscribe": {
"$ref": "#/components/messages/userSignedUp"
}
}
}
accounts.1.0.event.user.signup:
subscribe:
$ref: "#/components/messages/userSignedUp"
Describes the operations available on a single topic.
| Field Name | Type | Description |
|---|---|---|
| $ref | string | Allows for an external definition of this topic item. The referenced structure MUST be in the format of a Topic Item Object. If there are conflicts between the referenced definition and this Topic Item's definition, the behavior is undefined. |
| subscribe | Message Object | A definition of the message a SUBSCRIBE operation will receive on this topic. |
| publish | Message Object | A definition of the message a PUBLISH operation will receive on this topic. |
This object can be extended with Specification Extensions.
{
"subscribe": {
"summary": "A user signed up.",
"description": "A longer description of the message",
"payload": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/user"
},
"signup": {
"$ref": "#/components/schemas/signup"
}
}
}
}
}
subscribe:
summary: A user signed up.
description: A longer description of the message
payload:
type: object
properties:
user:
$ref: "#/components/schemas/user"
signup:
$ref: "#/components/schemas/signup"
Describes a message received on a given topic and operation.
| Field Name | Type | Description |
|---|---|---|
| headers | Schema Object | Definition of the message headers. It MAY or MAY NOT define the protocol headers. |
| payload | Schema Object | Definition of the message payload. |
| 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. |
This object can be extended with Specification Extensions.
{
"summary": "Action to sign a user up.",
"description": "A longer description",
"tags": [
{ "name": "user" },
{ "name": "signup" },
{ "name": "register" }
],
"headers": {
"type": "object",
"properties": {
"qos": {
"$ref": "#/components/schemas/MQTTQoSHeader"
},
"retainFlag": {
"$ref": "#/components/schemas/MQTTRetainHeader"
}
}
},
"payload": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/userCreate"
},
"signup": {
"$ref": "#/components/schemas/signup"
}
}
}
}
summary: Action to sign a user up.
description: A longer description
tags:
- name: user
- name: signup
- name: register
headers:
type: object
properties:
qos:
$ref: "#/components/schemas/MQTTQoSHeader"
retainFlag:
$ref: "#/components/schemas/MQTTRetainHeader"
payload:
type: object
properties:
user:
$ref: "#/components/schemas/userCreate"
signup:
$ref: "#/components/schemas/signup"
Allows adding meta data to a single tag.
| 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.
{
"name": "user",
"description": "User-related messages"
}
name: user
description: User-related messages
Allows referencing an external resource for extended documentation.
| 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.
{
"description": "Find more info here",
"url": "https://example.com"
}
description: Find more info here
url: https://example.com
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.
| 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.
{
"$ref": "#/components/schemas/Pet"
}
$ref: '#/components/schemas/Pet'
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.
| 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. |
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": {
"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": {
"type": "object",
"properties": {
"qos": {
"$ref": "#/components/schemas/MQTTQoSHeader"
},
"retainFlag": {
"$ref": "#/components/schemas/MQTTRetainHeader"
}
}
},
"payload": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/userCreate"
},
"signup": {
"$ref": "#/components/schemas/signup"
}
}
}
}
}
}
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:
type: object
properties:
qos:
$ref: "#/components/schemas/MQTTQoSHeader"
retainFlag:
$ref: "#/components/schemas/MQTTRetainHeader"
payload:
type: object
properties:
user:
$ref: "#/components/schemas/userCreate"
signup:
$ref: "#/components/schemas/signup"
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.
The following properties are taken directly from the JSON Schema definition and follow the same specifications:
The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification.
items MUST be present if the type is array.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:
| 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. |
| 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.
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.
The xml property allows extra definitions when translating the JSON definition to XML. The XML Object contains additional information about the available options.
{
"type": "string",
"format": "email"
}
type: string
format: email
{
"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
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'
{
"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
{
"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
{
"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
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.
| 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.
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.
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>
{
"animals": {
"type": "string",
"xml": {
"name": "animal"
}
}
}
animals:
type: string
xml:
name: animal
<animal>...</animal>
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>
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>
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 and HTTP API key.
| 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` |
| 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. |
This object MAY be extended with Specification Extensions.
{
"type": "userPassword"
}
type: userPassword
{
"type": "apiKey",
"in": "user"
}
type: apiKey,
in: user
{
"type": "X509"
}
type: X509
{
"type": "symmetricEncryption"
}
type: symmetricEncryption
{
"type": "http",
"scheme": "basic"
}
type: http
scheme: basic
{
"type": "httpApiKey",
"name": "api_key",
"in": "header"
}
type: httpApiKey
name: api_key
in: header
{
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
}
type: http
scheme: bearer
bearerFormat: JWT
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.
| 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. The value MUST be an empty array. |
{
"user_pass": []
}
user_pass: []
{
"api_key": []
}
api_key: []
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-".
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).
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. |
FAQs
AsyncAPI schema versions
The npm package asyncapi receives a total of 887 weekly downloads. As such, asyncapi popularity was classified as not popular.
We found that asyncapi demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.
Security News
Sonar’s acquisition of Tidelift highlights a growing industry shift toward sustainable open source funding, addressing maintainer burnout and critical software dependencies.
Security News
Ransomware negotiators share how modern cybercriminals operate like corporations, using specialized teams, negotiation tactics, and reputation management.