Check out the [supported schema formats table](#user-content-multiFormatSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#user-content-multiFormatSchemaFormatTable).
When using [Reference Objects](#user-content-referenceObject) within the schema, the `schemaFormat` of the referenced resource MUST match the `schemaFormat` of the schema containing the reference. +schemaFormat | `string` | **Required**. A string containing the name of the schema format that is used to define the information. If `schemaFormat` is missing, it MUST default to `application/vnd.aai.asyncapi+json;version={{asyncapi}}` where `{{asyncapi}}` matches the [AsyncAPI Version String](#user-content-A2SVersionString). In such a case, this would make the Multi Format Schema Object equivalent to the [Schema Object](#user-content-schemaObject). When using [Reference Object](#reference-object) within the schema, the `schemaFormat` of the resource being referenced MUST match the `schemaFormat` of the schema that contains the initial reference. For example, if you reference Avro `schema`, then `schemaFormat` of referencing resource and the resource being reference MUST match.
Check out the [supported schema formats table](#user-content-multiFormatSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#user-content-multiFormatSchemaFormatTable).
When using [Reference Objects](#reference-object) within the schema, the `schemaFormat` of the referenced resource MUST match the `schemaFormat` of the schema containing the reference. schema | `any` | **Required**. Definition of the message payload. It can be of any type but defaults to [Schema Object](#user-content-schemaObject). It MUST match the schema format defined in [`schemaFormat`](#user-content-multiFormatSchemaObjectSchemaFormat), including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string. -This object MAY be extended with [Specification Extensions](#user-content-specificationExtensions). +This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Schema formats table @@ -1855,17 +1855,17 @@ The following table contains a set of values that every implementation MUST supp Name | Allowed values | Notes ---|:---:|--- -[AsyncAPI 3.0.0 Schema Object](#user-content-schemaObject) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided. -[JSON Schema Draft 07](https://json-schema.org/specification-links.html#user-content-draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | +[AsyncAPI 3.0.0 Schema Object](#schema-object) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided. +[JSON Schema Draft 07](https://json-schema.org/specification-links.html#user-content-draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | The following table contains a set of values that every implementation is RECOMMENDED to support. Name | Allowed values | Notes ---|:---:|--- [Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#user-content-schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` | -[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#user-content-schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | +[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#user-content-schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | [RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` | -[Protocol Buffers](https://protobuf.dev/) | `application/vnd.google.protobuf;version=2`, `application/vnd.google.protobuf;version=3` | +[Protocol Buffers](https://protobuf.dev/) | `application/vnd.google.protobuf;version=2`, `application/vnd.google.protobuf;version=3` | #### Schema Object @@ -1917,21 +1917,21 @@ The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. - description - [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -- format - See [Data Type Formats](#user-content-dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. +- format - See [Data Type Formats](#data-type-formats) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. - default - Use it to specify that property has a predefined value if no other value is present. 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](#user-content-referenceObject) can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the `$ref` keyword MUST follow the behavior described by [Reference Object](#user-content-referenceObject) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#user-content-ref). +Alternatively, any time a Schema Object can be used, a [Reference Object](#reference-object) can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the `$ref` keyword MUST follow the behavior described by [Reference Object](#reference-object) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#user-content-ref). In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#user-content-schemaComposition) for more details. -externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#user-content-referenceObject) | Additional external documentation for this schema. +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](#composition-and-inheritance-(polymorphism)) for more details. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this schema. deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. -This object MAY be extended with [Specification Extensions](#user-content-specificationExtensions). +This object MAY be extended with [Specification Extensions](#specification-extensions). ###### Composition and Inheritance (Polymorphism) @@ -2359,11 +2359,11 @@ Field Name | Type | Applies To | Description 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](https://tools.ietf.org/html/rfc7235#user-content-section-5.1). 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](#user-content-oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. +flows | [OAuth Flows Object](#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 an absolute URL. scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. -This object MAY be extended with [Specification Extensions](#user-content-specificationExtensions). +This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Security Scheme Object Example @@ -2514,12 +2514,12 @@ Allows configuration of the supported OAuth Flows. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -implicit| [OAuth Flow Object](#user-content-oauthFlowObject) | Configuration for the OAuth Implicit flow. -password| [OAuth Flow Object](#user-content-oauthFlowObject) | Configuration for the OAuth Resource Owner Protected Credentials flow. -clientCredentials| [OAuth Flow Object](#user-content-oauthFlowObject) | Configuration for the OAuth Client Credentials flow. -authorizationCode| [OAuth Flow Object](#user-content-oauthFlowObject) | Configuration for the OAuth Authorization Code flow. +implicit| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Implicit flow. +password| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Resource Owner Protected Credentials flow. +clientCredentials| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. +authorizationCode| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. -This object MAY be extended with [Specification Extensions](#user-content-specificationExtensions). +This object MAY be extended with [Specification Extensions](#specification-extensions). #### OAuth Flow Object @@ -2533,7 +2533,7 @@ Field Name | Type | Applies To | Description refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. -This object MAY be extended with [Specification Extensions](#user-content-specificationExtensions). +This object MAY be extended with [Specification Extensions](#specification-extensions). ##### OAuth Flow Object Examples @@ -2560,18 +2560,18 @@ availableScopes: ### Correlation ID Object -An object that specifies an identifier at design time that can used for message tracing and correlation. +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](#user-content-runtimeExpression) is used. +For specifying and computing the location of a Correlation ID, a [runtime expression](#runtime-expression) is used. ##### Fixed Fields Field Name | Type | Description ---|:---|--- description | `string` | An optional description of the identifier. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -location | `string` | **REQUIRED.** A [runtime expression](#user-content-runtimeExpression) that specifies the location of the correlation ID. +location | `string` | **REQUIRED.** A [runtime expression](#runtime-expression) that specifies the location of the correlation ID. -This object MAY be extended with [Specification Extensions](#user-content-specificationExtensions). +This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Examples @@ -2590,7 +2590,7 @@ 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](#user-content-correlationIdObject) and [Operation Reply Address Object](#user-content-operationReplyAddressObject). +This mechanism is used by [Correlation ID Object](#user-content-correlationIdObject) and [Operation Reply Address Object](#operation-reply-address-object). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: @@ -2663,7 +2663,7 @@ Tools that do not recognize a specific `format` MAY default back to the `type` a The formats defined by the AsyncAPI Specification are: -Common Name | `type` | [`format`](#user-content-dataTypeFormat) | Comments +Common Name | `type` | [`format`](#data-type-formats) | Comments ----------- | ------ | -------- | -------- integer | `integer` | `int32` | signed 32 bits long | `integer` | `int64` | signed 64 bits diff --git a/spec/result.md b/spec/result.md new file mode 100644 index 000000000..9fe1750cc --- /dev/null +++ b/spec/result.md @@ -0,0 +1,2678 @@ +# AsyncAPI Specification + +#### Attribution + +Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). + +#### Version 3.0.0 + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). + +The AsyncAPI Specification is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). + +## Introduction + +The AsyncAPI Specification is a project used to describe message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). + +The AsyncAPI Specification defines a set of fields that can be used in an AsyncAPI document to describe an [application](#application)'s API. The document may reference other files for additional details or shared fields, but it is typically a single, primary document that encapsulates the API description. + +The AsyncAPI document SHOULD describe the operations an [application](#application) performs. For instance, consider the following AsyncAPI definition snippet: + +```yaml +channels: + userSignedUp: + # ...(redacted for brevity) +operations: + onUserSignedUp: + action: receive + channel: + $ref: "#/channels/userSignedUp" +``` + +It means that the [application](#user-content-definitionsApplication) will receive messages from the `userSignedUp` [channel](#channel). + +**The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol. + +It's NOT RECOMMENDED to derive a [receiver](#user-content-definitionsReceiver) AsyncAPI document from a [sender](#sender) one or vice versa. There are no guarantees that the channel used by an application to receive messages will be the same channel where another application is sending them. Also, certain fields in the document like `summary`, `description`, and the id of the operation might stop making sense. For instance, given the following receiver snippet: + +```yaml +operations: + onUserSignedUp: + summary: On user signed up. + description: Event received when a user signed up on the product. + action: receive + channel: + $ref: "#/channels/userSignedUp" +``` + +We can't automatically assume that an _opposite_ application exists by simply replacing `receive` with `send`: + +```yaml +operations: + onUserSignedUp: # <-- This doesn't make sense now. Should be something like sendUserSignedUp. + summary: On user signed up. # <-- This doesn't make sense now. Should say something like "Sends a user signed up event". + description: Event received when a user signed up on the product. # <-- This doesn't make sense now. Should speak about sending an event, not receiving it. + action: send + channel: + $ref: "#/channels/userSignedUp" +``` + +Aside from the issues mentioned above, there may also be infrastructure configuration that is not represented here. For instance, a system may use a read-only channel for receiving messages, a different one for sending them, and an intermediary process that will forward messages from one channel to the other. + +## Table of Contents + + +- [Definitions](#definitions) + - [Server](#server) + - [Application](#application) + - [Sender](#sender) + - [Receiver](#receiver) + - [Message](#message) + - [Channel](#channel) + - [Protocol](#protocol) +- [Specification](#specification) + - [Format](#format) + - [File Structure](#file-structure) + - [Absolute URLs](#absolute-urls) + - [Schema](#schema) + - [AsyncAPI Object](#asyncapi-object) + - [AsyncAPI Version String](#asyncapi-version-string) + - [Identifier](#identifier) + - [Info Object](#info-object) + - [Contact Object](#contact-object) + - [License Object](#license-object) + - [Servers Object](#servers-object) + - [Server Object](#server-object) + - [Server Variable Object](#server-variable-object) + - [Default Content Type](#default-content-type) + - [Channels Object](#channels-object) + - [Channel Object](#channel-object) + - [Operations Object](#operations-object) + - [Operation Object](#operation-object) + - [Operation Trait Object](#operation-trait-object) + - [Operation Reply Object](#operation-reply-object) + - [Operation Reply Address Object](#operation-reply-address-object) + - [Message Object](#message-object) + - [Message Trait Object](#message-trait-object) + - [Message Example Object](#message-example-object) + - [Tags Object](#tags-object) + - [Tag Object](#user-content-tag-object) + - [External Documentation Object](#external-documentation-object) + - [Components Object](#components-object) + - [Reference Object](#reference-object) + - [Multi Format Schema Object](#multi-format-schema-object) + - [Schema Object](#schema-object) + - [Security Scheme Object](#security-scheme-object) + - [OAuth Flows Object](#user-content-oauth-flows-object) + - [OAuth Flow Object](#user-content-oauth-flow-object) + - [Server Bindings Object](#server-bindings-object) + - [Parameters Object](#parameters-object) + - [Parameter Object](#parameter-object) + - [Channel Bindings Object](#channel-bindings-object) + - [Operation Bindings Object](#operation-bindings-object) + - [Message Bindings Object](#message-bindings-object) + - [Correlation ID Object](#correlation-id-object) + - [Specification Extensions](#specification-extensions) + + + +## Definitions + +### Server +A server MAY be a message broker that is capable of sending and/or receiving between a [sender](#user-content-definitionsSender) and [receiver](#receiver). A server MAY be a service with WebSocket API that enables message-driven communication between browser-to-server or server-to-server. + +### Application +An application is any kind of computer program or a group of them. It MUST be a [sender](#user-content-definitionsSender), a [receiver](#user-content-definitionsReceiver), or both. An application MAY be a microservice, IoT device (sensor), mainframe process, message broker, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#user-content-definitionsProtocol). An application MUST also use a protocol supported by the [server](#user-content-definitionsServer) in order to connect and exchange [messages](#message). + +### Sender +A sender is a type of application, that is sending [messages](#user-content-definitionsMessage) to [channels](#user-content-definitionsChannel). A sender MAY send to multiple channels depending on the [server](#server), protocol, and use-case pattern. + +### Receiver +A receiver is a type of application that is receiving [messages](#user-content-definitionsMessage) from [channels](#user-content-definitionsChannel). A receiver MAY receive from multiple channels depending on the [server](#server), protocol, and the use-case pattern. A receiver MAY forward a received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and forwards them. + +### Message +A message is the mechanism by which information is exchanged via a channel between [servers](#user-content-definitionsServer) and applications. A message MAY contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#protocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. + +### Channel +A channel is an addressable component, made available by the [server](#server), for the organization of [messages](#user-content-definitionsMessage). [Sender](#user-content-definitionsSender) applications send messages to channels and [receiver](#user-content-definitionsReceiver) applications receive messages from channels. [Servers](#server) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#server) implementation, the channel MAY be included in the message via protocol-defined headers. + +### Protocol +A protocol is the mechanism (wireline protocol or API) by which [messages](#user-content-definitionsMessage) are exchanged between the application and the [channel](#channel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket, Google Pub/Sub, Pulsar. + +### Bindings +A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only. + +## Specification + +### Format + +The files describing the message-driven API in accordance with the AsyncAPI Specification are represented as JSON objects and conform to the JSON standards. +YAML, being a superset of JSON, can be used as well to represent a A2S (AsyncAPI Specification) file. + +For example, if a field is said to have an array value, the JSON array representation will be used: + +```yaml +{ + "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](https://www.yaml.org/spec/1.2/spec.html) is recommended along with some additional constraints: + +- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://www.yaml.org/spec/1.2/spec.html#user-content-id2803231) +- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset + +### File Structure + +An AsyncAPI document MAY be made up of a single document or be divided into multiple, +connected parts at the discretion of the author. In the latter case, [Reference Objects](#reference-object) are used. + +It is important to note that everything that is defined in an AsyncAPI document MUST be used by the implemented [Application](#application), with the exception of the [Components Object](#user-content-componentsObject). Everything that is defined inside the Components Object represents a resource that MAY or MAY NOT be used by the implemented [Application](#application). + +By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. + +### Absolute URLs + +Unless specified otherwise, all properties that are absolute URLs are defined by [RFC3986, section 4.3](https://datatracker.ietf.org/doc/html/rfc3986#user-content-section-4.3). + +### Schema + +#### AsyncAPI Object + +This is the root document object for the API specification. +It combines resource listing and API declaration together into one document. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +asyncapi | [AsyncAPI Version String](#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](#user-content-A2SIdString) | Identifier of the [application](#application) the AsyncAPI document is defining. +info | [Info Object](#info-object) | **REQUIRED.** Provides metadata about the API. The metadata can be used by the clients if needed. +servers | [Servers Object](#servers-object) | Provides connection details of servers. +defaultContentType | [Default Content Type](#default-content-type) | Default content type to use when encoding/decoding a message's payload. +channels | [Channels Object](#user-content-channelsObject) | The channels used by this [application](#application). +operations | [Operations Object](#user-content-operationsObject) | The operations this [application](#application) MUST implement. +components | [Components Object](#user-content-componentsObject) | An element to hold various reusable objects for the specification. Everything that is defined inside this object represents a resource that MAY or MAY NOT be used in the rest of the document and MAY or MAY NOT be used by the implemented [Application](#application). + +This object MAY be extended with [Specification Extensions](#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](#application) the AsyncAPI document is defining. It must conform to the URI format, according to [RFC3986](https://tools.ietf.org/html/rfc3986). + +It is RECOMMENDED to use a [URN](https://tools.ietf.org/html/rfc8141) to globally and uniquely identify the application during long periods of time, even after it becomes unavailable or ceases to exist. + +###### Examples + +```json +{ + "id": "urn:example:com:smartylighting:streetlights:server" +} +``` + +```yaml +id: 'urn:example:com:smartylighting:streetlights:server' +``` + +```json +{ + "id": "https://github.com/smartylighting/streetlights-server" +} +``` + +```yaml +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](https://spec.commonmark.org/) can be used for rich text representation. +termsOfService | `string` | A URL to the Terms of Service for the API. This MUST be in the form of an absolute URL. +contact | [Contact Object](#contact-object) | The contact information for the exposed API. +license | [License Object](#license-object) | The license information for the exposed API. +tags | [Tags Object](#tags-object) | A list of tags for application API documentation control. Tags can be used for logical grouping of applications. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation of the exposed API. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Info Object Example: + +```json +{ + "title": "AsyncAPI Sample App", + "version": "1.0.1", + "description": "This is a sample app.", + "termsOfService": "https://asyncapi.org/terms/", + "contact": { + "name": "API Support", + "url": "https://www.asyncapi.org/support", + "email": "support@asyncapi.org" + }, + "license": { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + }, + "externalDocs": { + "description": "Find more info here", + "url": "https://www.asyncapi.org" + }, + "tags": [ + { + "name": "e-commerce" + } + ] +} +``` + +```yaml +title: AsyncAPI Sample App +version: 1.0.1 +description: This is a sample app. +termsOfService: https://asyncapi.org/terms/ +contact: + name: API Support + url: https://www.asyncapi.org/support + email: support@asyncapi.org +license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html +externalDocs: + description: Find more info here + url: https://www.asyncapi.org +tags: + - name: e-commerce +``` + +#### 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. This MUST be in the form of an absolute URL. +email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Contact Object Example: + +```json +{ + "name": "API Support", + "url": "https://www.example.com/support", + "email": "support@example.com" +} +``` + +```yaml +name: API Support +url: https://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. This MUST be in the form of an absolute URL. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### License Object Example: + +```json +{ + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" +} +``` + +```yaml +name: Apache 2.0 +url: https://www.apache.org/licenses/LICENSE-2.0.html +``` + +#### Servers Object + +The Servers Object is a map of [Server Objects](#server-object). + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +`^[A-Za-z0-9_\-]+$` | [Server Object](#user-content-serverObject) \| [Reference Object](#reference-object) | The definition of a server this application MAY connect to. + +##### Servers Object Example + +```json +{ + "development": { + "host": "localhost:5672", + "description": "Development AMQP broker.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:development", + "description": "This environment is meant for developers to run their own tests." + } + ] + }, + "staging": { + "host": "rabbitmq-staging.in.mycompany.com:5672", + "description": "RabbitMQ broker for the staging environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:staging", + "description": "This environment is a replica of the production environment." + } + ] + }, + "production": { + "host": "rabbitmq.in.mycompany.com:5672", + "description": "RabbitMQ broker for the production environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:production", + "description": "This environment is the live environment available for final users." + } + ] + } +} +``` + +```yaml +development: + host: localhost:5672 + description: Development AMQP broker. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:development" + description: "This environment is meant for developers to run their own tests." +staging: + host: rabbitmq-staging.in.mycompany.com:5672 + description: RabbitMQ broker for the staging environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:staging" + description: "This environment is a replica of the production environment." +production: + host: rabbitmq.in.mycompany.com:5672 + description: RabbitMQ broker for the production environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:production" + description: "This environment is the live environment available for final users." +``` + + +#### Server Object + +An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +host | `string` | **REQUIRED**. The server host name. It MAY include the port. This field supports [Server Variables](#user-content-serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. +protocol | `string` | **REQUIRED**. The protocol this server supports for connection. +protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. +pathname | `string` | The path to a resource in the host. This field supports [Server Variables](#user-content-serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. +description | `string` | An optional string describing the server. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +title | `string` | A human-friendly title for the server. +summary | `string` | A short summary of the server. +variables | Map[`string`, [Server Variable Object](#user-content-serverVariableObject) \| [Reference Object](#reference-object)]] | A map between a variable name and its value. The value is used for substitution in the server's `host` and `pathname` template. +security | [[Security Scheme Object](#security-scheme-object) \| [Reference Object](#user-content-referenceObject)] | A declaration of which security schemes can be used with this server. The list of values includes alternative [security scheme objects](#security-scheme-object) that can be used. Only one of the security scheme objects need to be satisfied to authorize a connection or operation. +tags | [Tags Object](#tags-object) | A list of tags for logical grouping and categorization of servers. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this server. +bindings | [Server Bindings Object](#user-content-serverBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server. + +##### Server Object Example + +A single server would be described as: + +```json +{ + "host": "kafka.in.mycompany.com:9092", + "description": "Production Kafka broker.", + "protocol": "kafka", + "protocolVersion": "3.2" +} +``` + +```yaml +host: kafka.in.mycompany.com:9092 +description: Production Kafka broker. +protocol: kafka +protocolVersion: '3.2' +``` + +An example of a server that has a `pathname`: + +```json +{ + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/production", + "protocol": "amqp", + "description": "Production RabbitMQ broker (uses the `production` vhost)." +} +``` + +```yaml +host: rabbitmq.in.mycompany.com:5672 +pathname: /production +protocol: amqp +description: Production RabbitMQ broker (uses the `production` vhost). +``` + +#### Server Variable Object + +An object representing a Server Variable for server URL template substitution. + +##### 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](https://spec.commonmark.org/) 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](#specification-extensions). + +##### Server Variable Object Example + +```json +{ + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/{env}", + "protocol": "amqp", + "description": "RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`.", + "variables": { + "env": { + "description": "Environment to connect to. It can be either `production` or `staging`.", + "enum": [ + "production", + "staging" + ] + } + } +} +``` + +```yaml +host: 'rabbitmq.in.mycompany.com:5672' +pathname: '/{env}' +protocol: amqp +description: RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`. +variables: + env: + description: Environment to connect to. It can be either `production` or `staging`. + enum: + - production + - staging +``` + + +#### Default Content Type + +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](#user-content-messageObjectContentType) 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 + +```json +{ + "defaultContentType": "application/json" +} +``` + +```yaml +defaultContentType: application/json +``` + + + + + + +#### Channels Object + +An object containing all the [Channel Object](#user-content-channelObject) definitions the [Application](#application) MUST use during runtime. + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +{channelId} | [Channel Object](#user-content-channelObject) \| [Reference Object](#reference-object) | An identifier for the described channel. The `channelId` value is **case-sensitive**. Tools and libraries MAY use the `channelId` to uniquely identify a channel, therefore, it is RECOMMENDED to follow common programming naming conventions. + +##### Channels Object Example + +```json +{ + "userSignedUp": { + "address": "user.signedup", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + } + } + } +} +``` + +```yaml +userSignedUp: + address: 'user.signedup' + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' +``` + + + + +#### Channel Object + +Describes a shared communication channel. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#user-content-channelAddressExpressions). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channel-bindings-object) to define them. +messages | [Messages Object](#user-content-messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#message-object) defined in this map.** +title | `string` | A human-friendly title for the channel. +summary | `string` | A short summary of the channel. +description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +servers | [[Reference Object](#user-content-referenceObject)] | An array of `$ref` pointers to the definition of the servers in which this channel is available. If the channel is located in the [root Channels Object](#user-content-channelsObject), it MUST point to a subset of server definitions located in the [root Servers Object](#user-content-serversObject), and MUST NOT point to a subset of server definitions located in the [Components Object](#user-content-componentsObject) or anywhere else. If the channel is located in the [Components Object](#user-content-componentsObject), it MAY point to a [Server Objects](#server-object) in any location. If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#user-content-serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#user-content-referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#server-object). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +parameters | [Parameters Object](#user-content-parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](#channel-address-expressions). +tags | [Tags Object](#tags-object) | A list of tags for logical grouping of channels. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this channel. +bindings | [Channel Bindings Object](#user-content-channelBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. + + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Channel Object Example + +```json +{ + "address": "users.{userId}", + "title": "Users channel", + "description": "This channel is used to exchange messages about user events.", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" + } + }, + "parameters": { + "userId": { + "$ref": "#/components/parameters/userId" + } + }, + "servers": [ + { "$ref": "#/servers/rabbitmqInProd" }, + { "$ref": "#/servers/rabbitmqInStaging" } + ], + "bindings": { + "amqp": { + "is": "queue", + "queue": { + "exclusive": true + } + } + }, + "tags": [{ + "name": "user", + "description": "User-related messages" + }], + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" + } +} +``` + +```yaml +address: 'users.{userId}' +title: Users channel +description: This channel is used to exchange messages about user events. +messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' +parameters: + userId: + $ref: '#/components/parameters/userId' +servers: + - $ref: '#/servers/rabbitmqInProd' + - $ref: '#/servers/rabbitmqInStaging' +bindings: + amqp: + is: queue + queue: + exclusive: true +tags: + - name: user + description: User-related messages +externalDocs: + description: 'Find more info here' + url: 'https://example.com' +``` + + + + + +#### Channel Address Expressions + +Channel addresses MAY contain expressions that can be used to define dynamic values. + +Expressions MUST be composed by a name enclosed in curly braces (`{` and `}`). E.g., `{userId}`. + + + + + +#### Messages Object + +Describes a map of messages included in a channel. + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +`{messageId}` | [Message Object](#user-content-messageObject) \| [Reference Object](#reference-object) | The key represents the message identifier. The `messageId` value is **case-sensitive**. Tools and libraries MAY use the `messageId` value to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. + +##### Messages Object Example + +```json +{ + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" + } +} +``` + +```yaml +userSignedUp: + $ref: '#/components/messages/userSignedUp' +userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' +``` + + + +#### Operations Object + +Holds a dictionary with all the [operations](#operation-object) this application MUST implement. + +> If you're looking for a place to define operations that MAY or MAY NOT be implemented by the application, consider defining them in [`components/operations`](#user-content-componentsOperations). + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +{operationId} | [Operation Object](#user-content-operationObject) \| [Reference Object](#reference-object) | The operation this application MUST implement. The field name (`operationId`) MUST be a string used to identify the operation in the document where it is defined, and its value is **case-sensitive**. Tools and libraries MAY use the `operationId` to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. + +##### Operations Object Example + +```json +{ + "onUserSignUp": { + "title": "User sign up", + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { "$ref": "#/components/operationTraits/kafka" } + ] + } +} +``` + +```yaml +onUserSignUp: + title: User sign up + summary: Action to sign a user up. + description: A longer description + channel: + $ref: '#/channels/userSignup' + action: send + tags: + - name: user + - name: signup + - name: register + bindings: + amqp: + ack: false + traits: + - $ref: '#/components/operationTraits/kafka' +``` + + +#### Operation Object + +Describes a specific operation. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +action | `"send"` &#user-content-124; `"receive"` | **Required**. Use `send` when it's expected that the application will send a message to the given [`channel`](#user-content-operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#user-content-operationObjectChannel). +channel | [Reference Object](#user-content-referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. If the operation is located in the [root Operations Object](#user-content-operationsObject), it MUST point to a channel definition located in the [root Channels Object](#user-content-channelsObject), and MUST NOT point to a channel definition located in the [Components Object](#user-content-componentsObject) or anywhere else. If the operation is located in the [Components Object](#user-content-componentsObject), it MAY point to a [Channel Object](#channel-object) in any location. Please note the `channel` property value MUST be a [Reference Object](#user-content-referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channel-object). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +title | `string` | A human-friendly title for the operation. +summary | `string` | A short summary of what the operation is about. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. +security | [[Security Scheme Object](#user-content-securitySchemeObject) \| [Reference Object](#user-content-referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#user-content-securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#user-content-serverObjectSecurity) also applies, it MUST also be satisfied. +tags | [Tags Object](#tags-object) | A list of tags for logical grouping and categorization of operations. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this operation. +bindings | [Operation Bindings Object](#user-content-operationBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. +traits | [[Operation Trait Object](#user-content-operationTraitObject) &#user-content-124; [Reference Object](#user-content-referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged using [traits merge mechanism](#user-content-traits-merge-mechanism). The resulting object MUST be a valid [Operation Object](#operation-object). +messages | [[Reference Object](#user-content-referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#message-object) that can be processed by this operation. It MUST contain a subset of the messages defined in the [channel referenced in this operation](#user-content-operationObjectChannel), and MUST NOT point to a subset of message definitions located in the [Messages Object](#user-content-componentsMessages) in the [Components Object](#user-content-componentsObject) or anywhere else. **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#message-object) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#user-content-referenceObject) and, therefore, MUST NOT contain [Message Objects](#message-object). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +reply | [Operation Reply Object](#user-content-operationReplyObject) &#user-content-124; [Reference Object](#reference-object) | The definition of the reply in a request-reply operation. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Operation Object Example + +```json +{ + "title": "User sign up", + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "security": [ + { + "petstore_auth": [ + "write:pets", + "read:pets" + ] + } + ], + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { "$ref": "#/components/operationTraits/kafka" } + ], + "messages": [ + { "$ref": "/components/messages/userSignedUp" } + ], + "reply": { + "address": { + "location": "$message.header#/replyTo" + }, + "channel": { + "$ref": "#/channels/userSignupReply" + }, + "messages": [ + { "$ref": "/components/messages/userSignedUpReply" } + ], + } +} +``` + +```yaml +title: User sign up +summary: Action to sign a user up. +description: A longer description +channel: + $ref: '#/channels/userSignup' +action: send +security: + - petstore_auth: + - write:pets + - read:pets +tags: + - name: user + - name: signup + - name: register +bindings: + amqp: + ack: false +traits: + - $ref: "#/components/operationTraits/kafka" +messages: + - $ref: '#/components/messages/userSignedUp' +reply: + address: + location: '$message.header#/replyTo' + channel: + $ref: '#/channels/userSignupReply' + messages: + - $ref: '#/components/messages/userSignedUpReply' +``` + + + + +#### Operation Trait Object + +Describes a trait that MAY be applied to an [Operation Object](#operation-object). This object MAY contain any property from the [Operation Object](#operation-object), except the `action`, `channel`, `messages` and `traits` ones. + +If you're looking to apply traits to a message, see the [Message Trait Object](#message-trait-object). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +title | `string` | A human-friendly title for the operation. +summary | `string` | A short summary of what the operation is about. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +security | [[Security Scheme Object](#user-content-securitySchemeObject) \| [Reference Object](#user-content-referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#user-content-securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#user-content-serverObjectSecurity) also applies, it MUST also be satisfied. +tags | [Tags Object](#tags-object) | A list of tags for logical grouping and categorization of operations. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this operation. +bindings | [Operation Bindings Object](#user-content-operationBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Operation Trait Object Example + +```json +{ + "bindings": { + "amqp": { + "ack": false + } + } +} +``` + +```yaml +bindings: + amqp: + ack: false +``` + + + + +#### Operation Reply Object + +Describes the reply part that MAY be applied to an Operation Object. If an operation implements the request/reply pattern, the reply object represents the response message. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +address | [Operation Reply Address Object](#user-content-operationReplyAddressObject) &#user-content-124; [Reference Object](#reference-object) | Definition of the address that implementations MUST use for the reply. +channel | [Reference Object](#user-content-referenceObject) | A `$ref` pointer to the definition of the channel in which this operation is performed. When [address](#user-content-operationReplyAddressObject) is specified, the [`address` property](#channel-objectAddress) of the channel referenced by this property MUST be either `null` or not defined. If the operation reply is located inside a [root Operation Object](#user-content-operationObject), it MUST point to a channel definition located in the [root Channels Object](#user-content-channelsObject), and MUST NOT point to a channel definition located in the [Components Object](#user-content-componentsObject) or anywhere else. If the operation reply is located inside an [Operation Object] in the [Components Object](#user-content-componentsObject) or in the [Replies Object](#user-content-componentsReplies) in the [Components Object](#user-content-componentsObject), it MAY point to a [Channel Object](#channel-object) in any location. Please note the `channel` property value MUST be a [Reference Object](#user-content-referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channel-object). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +messages | [[Reference Object](#user-content-referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#message-object) that can be processed by this operation as reply. It MUST contain a subset of the messages defined in the [channel referenced in this operation reply](#user-content-operationObjectChannel), and MUST NOT point to a subset of message definitions located in the [Components Object](#user-content-componentsObject) or anywhere else. **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#message-object) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#user-content-referenceObject) and, therefore, MUST NOT contain [Message Objects](#message-object). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +#### Operation Reply Address Object + +An object that specifies where an operation has to send the reply. + +For specifying and computing the location of a reply address, a [runtime expression](#runtime-expression) is used. + + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- +description | `string` | An optional description of the address. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +location | `string` | **REQUIRED.** A [runtime expression](#runtime-expression) that specifies the location of the reply address. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Examples + +```json +{ + "description": "Consumer inbox", + "location": "$message.header#/replyTo" +} +``` + +```yaml +description: Consumer Inbox +location: $message.header#/replyTo +``` + + +#### Parameters Object + +Describes a map of parameters included in a channel address. + +This map MUST contain all the parameters used in the parent channel address. + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +`^[A-Za-z0-9_\-]+$` | [Parameter Object](#user-content-parameterObject) &#user-content-124; [Reference Object](#reference-object) | The key represents the name of the parameter. It MUST match the parameter name used in the parent channel address. + +##### Parameters Object Example + +```json +{ + "address": "user/{userId}/signedup", + "parameters": { + "userId": { + "description": "Id of the user." + } + } +} +``` + +```yaml +address: user/{userId}/signedup +parameters: + userId: + description: Id of the user. +``` + + + + + +#### Parameter Object + +Describes a parameter included in a channel address. + +##### 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 parameter. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +examples | [`string`] | An array of examples of the parameter value. +location | `string` | A [runtime expression](#runtime-expression) that specifies the location of the parameter value. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Parameter Object Example + +```json +{ + "address": "user/{userId}/signedup", + "parameters": { + "userId": { + "description": "Id of the user.", + "location": "$message.payload#/user/id" + } + } +} +``` + +```yaml +address: user/{userId}/signedup +parameters: + userId: + description: Id of the user. + location: $message.payload#/user/id +``` + + + + +#### Server Bindings Object + +Map describing protocol-specific definitions for a server. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Server Binding](https://github.com/asyncapi/bindings/blob/master/http#user-content-server) | Protocol-specific information for an HTTP server. +`ws` | [WebSockets Server Binding](https://github.com/asyncapi/bindings/blob/master/websockets#user-content-server) | Protocol-specific information for a WebSockets server. +`kafka` | [Kafka Server Binding](https://github.com/asyncapi/bindings/blob/master/kafka#user-content-server) | Protocol-specific information for a Kafka server. +`anypointmq` | [Anypoint MQ Server Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq#user-content-server) | Protocol-specific information for an Anypoint MQ server. +`amqp` | [AMQP Server Binding](https://github.com/asyncapi/bindings/blob/master/amqp#user-content-server) | Protocol-specific information for an AMQP 0-9-1 server. +`amqp1` | [AMQP 1.0 Server Binding](https://github.com/asyncapi/bindings/blob/master/amqp1#user-content-server) | Protocol-specific information for an AMQP 1.0 server. +`mqtt` | [MQTT Server Binding](https://github.com/asyncapi/bindings/blob/master/mqtt#user-content-server) | Protocol-specific information for an MQTT server. +`mqtt5` | [MQTT 5 Server Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5#user-content-server) | Protocol-specific information for an MQTT 5 server. +`nats` | [NATS Server Binding](https://github.com/asyncapi/bindings/blob/master/nats#user-content-server) | Protocol-specific information for a NATS server. +`jms` | [JMS Server Binding](https://github.com/asyncapi/bindings/blob/master/jms#user-content-server) | Protocol-specific information for a JMS server. +`sns` | [SNS Server Binding](https://github.com/asyncapi/bindings/blob/master/sns#user-content-server) | Protocol-specific information for an SNS server. +`solace` | [Solace Server Binding](https://github.com/asyncapi/bindings/blob/master/solace#user-content-server) | Protocol-specific information for a Solace server. +`sqs` | [SQS Server Binding](https://github.com/asyncapi/bindings/blob/master/sqs#user-content-server) | Protocol-specific information for an SQS server. +`stomp` | [STOMP Server Binding](https://github.com/asyncapi/bindings/blob/master/stomp#user-content-server) | Protocol-specific information for a STOMP server. +`redis` | [Redis Server Binding](https://github.com/asyncapi/bindings/blob/master/redis#user-content-server) | Protocol-specific information for a Redis server. +`mercure` | [Mercure Server Binding](https://github.com/asyncapi/bindings/blob/master/mercure#user-content-server) | Protocol-specific information for a Mercure server. +`ibmmq` | [IBM MQ Server Binding](https://github.com/asyncapi/bindings/blob/master/ibmmq#user-content-server-binding-object) | Protocol-specific information for an IBM MQ server. +`googlepubsub` | [Google Cloud Pub/Sub Server Binding](https://github.com/asyncapi/bindings/blob/master/googlepubsub#user-content-server) | Protocol-specific information for a Google Cloud Pub/Sub server. +`pulsar` | [Pulsar Server Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#user-content-server-binding-object) | Protocol-specific information for a Pulsar server. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + + + +#### Channel Bindings Object + +Map describing protocol-specific definitions for a channel. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Channel Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#user-content-channel) | Protocol-specific information for an HTTP channel. +`ws` | [WebSockets Channel Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#user-content-channel) | Protocol-specific information for a WebSockets channel. +`kafka` | [Kafka Channel Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#user-content-channel) | Protocol-specific information for a Kafka channel. +`anypointmq` | [Anypoint MQ Channel Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#user-content-channel) | Protocol-specific information for an Anypoint MQ channel. +`amqp` | [AMQP Channel Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#user-content-channel) | Protocol-specific information for an AMQP 0-9-1 channel. +`amqp1` | [AMQP 1.0 Channel Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#user-content-channel) | Protocol-specific information for an AMQP 1.0 channel. +`mqtt` | [MQTT Channel Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#user-content-channel) | Protocol-specific information for an MQTT channel. +`mqtt5` | [MQTT 5 Channel Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5#user-content-channel) | Protocol-specific information for an MQTT 5 channel. +`nats` | [NATS Channel Binding](https://github.com/asyncapi/bindings/blob/master/nats/README.md#user-content-channel) | Protocol-specific information for a NATS channel. +`jms` | [JMS Channel Binding](https://github.com/asyncapi/bindings/blob/master/jms/README.md#user-content-channel) | Protocol-specific information for a JMS channel. +`sns` | [SNS Channel Binding](https://github.com/asyncapi/bindings/blob/master/sns/README.md#user-content-channel) | Protocol-specific information for an SNS channel. +`solace` | [Solace Channel Binding](https://github.com/asyncapi/bindings/blob/master/solace#user-content-channel) | Protocol-specific information for a Solace channel. +`sqs` | [SQS Channel Binding](https://github.com/asyncapi/bindings/blob/master/sqs/README.md#user-content-channel) | Protocol-specific information for an SQS channel. +`stomp` | [STOMP Channel Binding](https://github.com/asyncapi/bindings/blob/master/stomp/README.md#user-content-channel) | Protocol-specific information for a STOMP channel. +`redis` | [Redis Channel Binding](https://github.com/asyncapi/bindings/blob/master/redis#user-content-channel) | Protocol-specific information for a Redis channel. +`mercure` | [Mercure Channel Binding](https://github.com/asyncapi/bindings/blob/master/mercure#user-content-channel) | Protocol-specific information for a Mercure channel. +`ibmmq` | [IBM MQ Channel Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#user-content-channel-binding-object) | Protocol-specific information for an IBM MQ channel. +`googlepubsub` | [Google Cloud Pub/Sub Channel Binding](https://github.com/asyncapi/bindings/tree/master/googlepubsub#user-content-channel) | Protocol-specific information for a Google Cloud Pub/Sub channel. +`pulsar` | [Pulsar Channel Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#user-content-channel-binding-object) | Protocol-specific information for a Pulsar channel. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + + + +#### Operation Bindings Object + +Map describing protocol-specific definitions for an operation. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Operation Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#user-content-operation) | Protocol-specific information for an HTTP operation. +`ws` | [WebSockets Operation Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#user-content-operation) | Protocol-specific information for a WebSockets operation. +`kafka` | [Kafka Operation Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#user-content-operation) | Protocol-specific information for a Kafka operation. +`anypointmq` | [Anypoint MQ Operation Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#user-content-operation) | Protocol-specific information for an Anypoint MQ operation. +`amqp` | [AMQP Operation Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#user-content-operation) | Protocol-specific information for an AMQP 0-9-1 operation. +`amqp1` | [AMQP 1.0 Operation Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#user-content-operation) | Protocol-specific information for an AMQP 1.0 operation. +`mqtt` | [MQTT Operation Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#user-content-operation) | Protocol-specific information for an MQTT operation. +`mqtt5` | [MQTT 5 Operation Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5/README.md#user-content-operation) | Protocol-specific information for an MQTT 5 operation. +`nats` | [NATS Operation Binding](https://github.com/asyncapi/bindings/blob/master/nats/README.md#user-content-operation) | Protocol-specific information for a NATS operation. +`jms` | [JMS Operation Binding](https://github.com/asyncapi/bindings/blob/master/jms/README.md#user-content-operation) | Protocol-specific information for a JMS operation. +`sns` | [SNS Operation Binding](https://github.com/asyncapi/bindings/blob/master/sns/README.md#user-content-operation) | Protocol-specific information for an SNS operation. +`solace` | [Solace Operation Binding](https://github.com/asyncapi/bindings/blob/master/solace#user-content-operation) | Protocol-specific information for a Solace operation. +`sqs` | [SQS Operation Binding](https://github.com/asyncapi/bindings/blob/master/sqs/README.md#user-content-operation) | Protocol-specific information for an SQS operation. +`stomp` | [STOMP Operation Binding](https://github.com/asyncapi/bindings/blob/master/stomp/README.md#user-content-operation) | Protocol-specific information for a STOMP operation. +`redis` | [Redis Operation Binding](https://github.com/asyncapi/bindings/blob/master/redis#user-content-operation) | Protocol-specific information for a Redis operation. +`mercure` | [Mercure Operation Binding](https://github.com/asyncapi/bindings/blob/master/mercure#user-content-operation) | Protocol-specific information for a Mercure operation. +`googlepubsub` | [Google Cloud Pub/Sub Operation Binding](https://github.com/asyncapi/bindings/blob/master/googlepubsub#user-content-operation) | Protocol-specific information for a Google Cloud Pub/Sub operation. +`ibmmq` | [IBM MQ Operation Binding](https://github.com/asyncapi/bindings/blob/master/ibmmq#user-content-operation-binding-object) | Protocol-specific information for an IBM MQ operation. +`pulsar` | [Pulsar Operation Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#user-content-operation-binding-fields) | Protocol-specific information for a Pulsar operation. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + + + + +#### Message Bindings Object + +Map describing protocol-specific definitions for a message. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Message Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#user-content-message) | Protocol-specific information for an HTTP message, i.e., a request or a response. +`ws` | [WebSockets Message Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#user-content-message) | Protocol-specific information for a WebSockets message. +`kafka` | [Kafka Message Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#user-content-message) | Protocol-specific information for a Kafka message. +`anypointmq` | [Anypoint MQ Message Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#user-content-message) | Protocol-specific information for an Anypoint MQ message. +`amqp` | [AMQP Message Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#user-content-message) | Protocol-specific information for an AMQP 0-9-1 message. +`amqp1` | [AMQP 1.0 Message Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#user-content-message) | Protocol-specific information for an AMQP 1.0 message. +`mqtt` | [MQTT Message Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#user-content-message) | Protocol-specific information for an MQTT message. +`mqtt5` | [MQTT 5 Message Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5/README.md#user-content-message) | Protocol-specific information for an MQTT 5 message. +`nats` | [NATS Message Binding](https://github.com/asyncapi/bindings/blob/master/nats/README.md#user-content-message) | Protocol-specific information for a NATS message. +`jms` | [JMS Message Binding](https://github.com/asyncapi/bindings/blob/master/jms/README.md#user-content-message) | Protocol-specific information for a JMS message. +`sns` | [SNS Message Binding](https://github.com/asyncapi/bindings/blob/master/sns/README.md#user-content-message) | Protocol-specific information for an SNS message. +`solace` | [Solace Server Binding](https://github.com/asyncapi/bindings/blob/master/solace#user-content-message) | Protocol-specific information for a Solace message. +`sqs` | [SQS Message Binding](https://github.com/asyncapi/bindings/blob/master/sqs/README.md#user-content-message) | Protocol-specific information for an SQS message. +`stomp` | [STOMP Message Binding](https://github.com/asyncapi/bindings/blob/master/stomp/README.md#user-content-message) | Protocol-specific information for a STOMP message. +`redis` | [Redis Message Binding](https://github.com/asyncapi/bindings/blob/master/redis#user-content-message) | Protocol-specific information for a Redis message. +`mercure` | [Mercure Message Binding](https://github.com/asyncapi/bindings/blob/master/mercure#user-content-message) | Protocol-specific information for a Mercure message. +`ibmmq` | [IBM MQ Message Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#user-content-message-binding-object) | Protocol-specific information for an IBM MQ message. +`googlepubsub` | [Google Cloud Pub/Sub Message Binding](https://github.com/asyncapi/bindings/tree/master/googlepubsub#user-content-message) | Protocol-specific information for a Google Cloud Pub/Sub message. +`pulsar` | [Pulsar Message Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#user-content-message-binding-fields) | Protocol-specific information for a Pulsar message. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + + + + + + + +#### Message Object + +Describes a message received on a given channel and operation. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +headers | [Multi Format Schema Object](#user-content-multiFormatSchemaObject) &#user-content-124; [Schema Object](#user-content-schemaObject) &#user-content-124; [Reference Object](#user-content-referenceObject) | Schema definition of the application headers. Schema MUST be a map of key-value pairs. It **MUST NOT** define the protocol headers. If this is a [Schema Object](#user-content-schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#asyncapi-version-string). +payload | [Multi Format Schema Object](#user-content-multiFormatSchemaObject) &#user-content-124; [Schema Object](#user-content-schemaObject) &#user-content-124; [Reference Object](#user-content-referenceObject) | Definition of the message payload. If this is a [Schema Object](#user-content-schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#asyncapi-version-string). +correlationId | [Correlation ID Object](#user-content-correlationIdObject) &#user-content-124; [Reference Object](#reference-object) | Definition of the correlation ID used for message tracing or matching. +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](#default-content-type) 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](https://spec.commonmark.org/) can be used for rich text representation. +tags | [Tags Object](#tags-object) | A list of tags for logical grouping and categorization of messages. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this message. +bindings | [Message Bindings Object](#user-content-messageBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. +examples | [[Message Example Object](#message-example-object)] | List of examples. +traits | [[Message Trait Object](#user-content-messageTraitObject) &#user-content-124; [Reference Object](#user-content-referenceObject)] | A list of traits to apply to the message object. Traits MUST be merged using [traits merge mechanism](#user-content-traits-merge-mechanism). The resulting object MUST be a valid [Message Object](#message-object). + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Message Object Example + +```json +{ + "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": { + "type": "object", + "properties": { + "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" + }, + "traits": [ + { "$ref": "#/components/messageTraits/commonHeaders" } + ], + "examples": [ + { + "name": "SimpleSignup", + "summary": "A simple UserSignup example message", + "headers": { + "correlationId": "my-correlation-id", + "applicationInstanceId": "myInstanceId" + }, + "payload": { + "user": { + "someUserKey": "someUserValue" + }, + "signup": { + "someSignupKey": "someSignupValue" + } + } + } + ] +} +``` + +```yaml +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: + type: object + properties: + 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 +traits: + - $ref: "#/components/messageTraits/commonHeaders" +examples: + - name: SimpleSignup + summary: A simple UserSignup example message + headers: + correlationId: my-correlation-id + applicationInstanceId: myInstanceId + payload: + user: + someUserKey: someUserValue + signup: + someSignupKey: someSignupValue +``` + +Example using Avro to define the payload: + +```json +{ + "name": "UserSignup", + "title": "User signup", + "summary": "Action to sign a user up.", + "description": "A longer description", + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "payload": { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "schema": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } +} +``` + +```yaml +name: UserSignup +title: User signup +summary: Action to sign a user up. +description: A longer description +tags: + - name: user + - name: signup + - name: register +payload: + schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' + schema: + $ref: 'path/to/user-create.avsc/#user-content-UserCreate' +``` + + + + + + + +#### Message Trait Object + +Describes a trait that MAY be applied to a [Message Object](#message-object). This object MAY contain any property from the [Message Object](#message-object), except `payload` and `traits`. + +If you're looking to apply traits to an operation, see the [Operation Trait Object](#operation-trait-object). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +headers | [Multi Format Schema Object](#user-content-multiFormatSchemaObject) &#user-content-124; [Schema Object](#user-content-schemaObject) &#user-content-124; [Reference Object](#user-content-referenceObject) | Schema definition of the application headers. Schema MUST be a map of key-value pairs. It **MUST NOT** define the protocol headers. If this is a [Schema Object](#user-content-schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#asyncapi-version-string). +correlationId | [Correlation ID Object](#user-content-correlationIdObject) &#user-content-124; [Reference Object](#reference-object) | Definition of the correlation ID used for message tracing or matching. +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](#default-content-type) 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](https://spec.commonmark.org/) can be used for rich text representation. +tags | [Tags Object](#tags-object) | A list of tags for logical grouping and categorization of messages. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this message. +bindings | [Message Bindings Object](#user-content-messageBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. +examples | [[Message Example Object](#message-example-object)] | List of examples. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Message Trait Object Example + +```json +{ + "contentType": "application/json" +} +``` + +```yaml +contentType: application/json +``` + +#### Message Example Object + +Message Example Object represents an example of a [Message Object](#message-object) and MUST contain either **headers** and/or **payload** fields. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +headers | `Map[string, any]` | The value of this field MUST validate against the [Message Object's headers](#user-content-messageObjectHeaders) field. +payload | `Map[string, any]` | The value of this field MUST validate against the [Message Object's payload](#user-content-messageObjectPayload) field. +name | `string` | A machine-friendly name. +summary | `string` | A short summary of what the example is about. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Message Example Object Example + +```json +{ + "name": "SimpleSignup", + "summary": "A simple UserSignup example message", + "headers": { + "correlationId": "my-correlation-id", + "applicationInstanceId": "myInstanceId" + }, + "payload": { + "user": { + "someUserKey": "someUserValue" + }, + "signup": { + "someSignupKey": "someSignupValue" + } + } +} +``` + +```yaml +name: SimpleSignup +summary: A simple UserSignup example message +headers: + correlationId: my-correlation-id + applicationInstanceId: myInstanceId +payload: + user: + someUserKey: someUserValue + signup: + someSignupKey: someSignupValue +``` + +#### Tags Object + +A Tags object is a list of [Tag Objects](#user-content-tagObject). An [Tag Object](#user-content-tagObject) in a list can be referenced by [Reference Object](#reference-object). + +#### 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](https://spec.commonmark.org/) can be used for rich text representation. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this tag. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Tag Object Example + +```json +{ + "name": "user", + "description": "User-related messages" +} +``` + +```yaml +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](https://spec.commonmark.org/) can be used for rich text representation. +url | `string` | **REQUIRED.** The URL for the target documentation. This MUST be in the form of an absolute URL. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### External Documentation Object Example + +```json +{ + "description": "Find more info here", + "url": "https://example.com" +} +``` + +```yaml +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](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules. A JSON Reference SHALL only be used to refer to a schema that is formatted in either JSON or YAML. In the case of a YAML-formatted Schema, the JSON Reference SHALL be applied to the JSON representation of that schema. The JSON representation SHALL be made by applying the conversion described [here](#format). + +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 + +```json +{ + "$ref": "#/components/schemas/Pet" +} +``` + +```yaml + $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`, [Multi Format Schema Object](#user-content-multiFormatSchemaObject) \| [Schema Object](#user-content-schemaObject) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Schema Object](#user-content-schemaObject). If this is a [Schema Object](#user-content-schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#asyncapi-version-string). + servers | Map[`string`, [Server Object](#server-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Server Objects](#server-object). + channels | Map[`string`, [Channel Object](#channel-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Channel Objects](#channel-object). + operations | Map[`string`, [Operation Object](#operation-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Operation Objects](#operation-object). + messages | Map[`string`, [Message Object](#message-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Message Objects](#message-object). + securitySchemes| Map[`string`, [Security Scheme Object](#security-scheme-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Security Scheme Objects](#security-scheme-object). + serverVariables | Map[`string`, [Server Variable Object](#server-variable-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Server Variable Objects](#server-variable-object). + parameters | Map[`string`, [Parameter Object](#parameter-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Parameter Objects](#parameter-object). + correlationIds | Map[`string`, [Correlation ID Object](#correlation-id-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Correlation ID Objects](#correlation-id-object). +replies | Map[`string`, [Operation Reply Object](#operation-reply-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Operation Reply Objects](#operation-reply-object). + replyAddresses | Map[`string`, [Operation Reply Address Object](#operation-reply-address-object) &#user-content-124; [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Operation Reply Address Objects](#operation-reply-address-object). + externalDocs | Map[`string`, [External Documentation Object](#external-documentation-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [External Documentation Objects](#external-documentation-object). + tags | Map[`string`, [Tag Object](#tag-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Tag Objects](#tag-object). + operationTraits | Map[`string`, [Operation Trait Object](#operation-trait-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Operation Trait Objects](#operation-trait-object). + messageTraits | Map[`string`, [Message Trait Object](#message-trait-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Message Trait Objects](#message-trait-object). + serverBindings | Map[`string`, [Server Bindings Object](#server-bindings-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Server Bindings Objects](#server-bindings-object). + channelBindings | Map[`string`, [Channel Bindings Object](#channel-bindings-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Channel Bindings Objects](#channel-bindings-object). + operationBindings | Map[`string`, [Operation Bindings Object](#operation-bindings-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Operation Bindings Objects](#operation-bindings-object). + messageBindings | Map[`string`, [Message Bindings Object](#message-bindings-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Message Bindings Objects](#message-bindings-object). + +This object MAY be extended with [Specification Extensions](#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 + +```json +{ + "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" + } + } + }, + "AvroExample": { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "schema": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } + }, + "servers": { + "development": { + "host": "{stage}.in.mycompany.com:{port}", + "description": "RabbitMQ broker", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "variables": { + "stage": { + "$ref": "#/components/serverVariables/stage" + }, + "port": { + "$ref": "#/components/serverVariables/port" + } + } + } + }, + "serverVariables": { + "stage": { + "default": "demo", + "description": "This value is assigned by the service provider, in this example `mycompany.com`" + }, + "port": { + "enum": ["5671", "5672"], + "default": "5672" + } + }, + "channels": { + "user/signedup": { + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignUp" + } + } + } + }, + "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": { + "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": { + "description": "Id of the user." + } + }, + "correlationIds": { + "default": { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + } + }, + "messageTraits": { + "commonHeaders": { + "headers": { + "type": "object", + "properties": { + "my-app-header": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + } + } + } + } + } +} +``` + +```yaml +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 + AvroExample: + schemaFormat: application/vnd.apache.avro+json;version=1.9.0 + schema: + $ref: 'path/to/user-create.avsc/#user-content-UserCreate' + servers: + development: + host: "{stage}.in.mycompany.com:{port}" + description: RabbitMQ broker + protocol: amqp + protocolVersion: 0-9-1 + variables: + stage: + $ref: "#/components/serverVariables/stage" + port: + $ref: "#/components/serverVariables/port" + serverVariables: + stage: + default: demo + description: This value is assigned by the service provider, in this example `mycompany.com` + port: + enum: ["5671", "5672"] + default: "5672" + channels: + user/signedup: + subscribe: + message: + $ref: "#/components/messages/userSignUp" + 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: + 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: + description: Id of the user. + correlationIds: + default: + description: Default Correlation ID + location: $message.header#/correlationId + messageTraits: + commonHeaders: + headers: + type: object + properties: + my-app-header: + type: integer + minimum: 0 + maximum: 100 +``` + +#### Multi Format Schema Object + +The Multi Format Schema Object represents a schema definition. It differs from the [Schema Object](#schema-object) in that it supports multiple schema formats or languages (e.g., JSON Schema, Avro, etc.). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +schemaFormat | `string` | **Required**. A string containing the name of the schema format that is used to define the information. If `schemaFormat` is missing, it MUST default to `application/vnd.aai.asyncapi+json;version={{asyncapi}}` where `{{asyncapi}}` matches the [AsyncAPI Version String](#user-content-A2SVersionString). In such a case, this would make the Multi Format Schema Object equivalent to the [Schema Object](#user-content-schemaObject). When using [Reference Object](#reference-object) within the schema, the `schemaFormat` of the resource being referenced MUST match the `schemaFormat` of the schema that contains the initial reference. For example, if you reference Avro `schema`, then `schemaFormat` of referencing resource and the resource being reference MUST match.
Check out the [supported schema formats table](#user-content-multiFormatSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#user-content-multiFormatSchemaFormatTable).
When using [Reference Objects](#reference-object) within the schema, the `schemaFormat` of the referenced resource MUST match the `schemaFormat` of the schema containing the reference. +schema | `any` | **Required**. Definition of the message payload. It can be of any type but defaults to [Schema Object](#user-content-schemaObject). It MUST match the schema format defined in [`schemaFormat`](#user-content-multiFormatSchemaObjectSchemaFormat), including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Schema formats table + +The following table contains a set of values that every implementation MUST support. + +Name | Allowed values | Notes +---|:---:|--- +[AsyncAPI 3.0.0 Schema Object](#schema-object) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided. +[JSON Schema Draft 07](https://json-schema.org/specification-links.html#user-content-draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | + +The following table contains a set of values that every implementation is RECOMMENDED to support. + +Name | Allowed values | Notes +---|:---:|--- +[Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#user-content-schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` | +[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#user-content-schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | +[RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` | +[Protocol Buffers](https://protobuf.dev/) | `application/vnd.google.protobuf;version=2`, `application/vnd.google.protobuf;version=3` | + + +#### Schema Object + +The Schema Object allows the definition of input and output data types. +These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/). The empty schema (which allows any instance to validate) MAY be represented by the `boolean` value `true` and a schema which allows no instance to validate MAY be represented by the `boolean` value `false`. + +Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-handrews-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01). +Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. For other formats (e.g., Avro, RAML, etc) see [Multi Format Schema Object](#multiFormatSchemaObject). + +##### Properties + +The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such, any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to: + +- title +- type +- required +- multipleOf +- maximum +- exclusiveMaximum +- minimum +- exclusiveMinimum +- maxLength +- minLength +- pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#user-content-sec-7.8.5) dialect) +- maxItems +- minItems +- uniqueItems +- maxProperties +- minProperties +- enum +- const +- examples +- if / then / else +- readOnly +- writeOnly +- properties +- patternProperties +- additionalProperties +- additionalItems +- items +- propertyNames +- contains +- allOf +- oneOf +- anyOf +- not + +The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. + +- description - [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +- format - See [Data Type Formats](#data-type-formats) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. +- default - Use it to specify that property has a predefined value if no other value is present. 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](#reference-object) can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the `$ref` keyword MUST follow the behavior described by [Reference Object](#reference-object) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#user-content-ref). + +In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#composition-and-inheritance-(polymorphism)) for more details. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this schema. + deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. + +This object MAY be extended with [Specification Extensions](#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 two ways to define the value of a discriminator for an inheriting instance. + +- Use the schema's name. +- Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. + +As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. + +##### Schema Object Examples + +###### Primitive Sample + +```json +{ + "type": "string", + "format": "email" +} +``` + +```yaml +type: string +format: email +``` + +###### Simple Model + +```json +{ + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "address": { + "$ref": "#/components/schemas/Address" + }, + "age": { + "type": "integer", + "format": "int32", + "minimum": 0 + } + } +} +``` + +```yaml +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: + +```json +{ + "type": "object", + "additionalProperties": { + "type": "string" + } +} +``` + +```yaml +type: object +additionalProperties: + type: string +``` + +For a string to model mapping: + +```json +{ + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/ComplexModel" + } +} +``` + +```yaml +type: object +additionalProperties: + $ref: '#/components/schemas/ComplexModel' +``` + +###### Model with Example + +```json +{ + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "examples": [ + { + "name": "Puma", + "id": 1 + } + ] +} +``` + +```yaml +type: object +properties: + id: + type: integer + format: int64 + name: + type: string +required: +- name +examples: +- name: Puma + id: 1 +``` + +###### Model with Boolean Schemas + +```json +{ + "type": "object", + "required": [ + "anySchema" + ], + "properties": { + "anySchema": true, + "cannotBeDefined": false + } +} +``` + +```yaml +type: object +required: +- anySchema +properties: + anySchema: true + cannotBeDefined: false +``` + +###### Models with Composition + +```json +{ + "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" + } + } + } + ] + } + } +} +``` + +```yaml +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 + +```json +{ + "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" + ] + } + ] + }, + "StickInsect": { + "description": "A representation of an Australian walking stick. Note that `StickBug` will be used as the discriminator value.", + "allOf": [ + { + "$ref": "#/components/schemas/Pet" + }, + { + "type": "object", + "properties": { + "petType": { + "const": "StickBug" + }, + "color": { + "type": "string" + } + }, + "required": [ + "color" + ] + } + ] + } + } +} +``` + +```yaml +schemas: + Pet: + type: object + discriminator: petType + properties: + name: + type: string + petType: + type: string + required: + - name + - petType + ## applies to instances with `petType: "Cat"` + ## because that is the schema name + Cat: + 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 + ## applies to instances with `petType: "Dog"` + ## because that is the schema name + Dog: + 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 + ## applies to instances with `petType: "StickBug"` + ## because that is the required value of the discriminator field, + ## overriding the schema name + StickInsect: + description: A representation of an Australian walking stick + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + properties: + petType: + const: StickBug + color: + type: string + required: + - color +``` + + + + + +#### Security Scheme Object + +Defines a security scheme that can be used by the operations. Supported schemes are: + +* User/Password. +* API key (either as user or as password). +* X.509 certificate. +* End-to-end encryption (either symmetric or asymmetric). +* HTTP authentication. +* HTTP API key. +* OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749). +* [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). +* SASL (Simple Authentication and Security Layer) as defined in [RFC4422](https://tools.ietf.org/html/rfc4422). + +##### 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"`, `"oauth2"`, `"openIdConnect"`, `"plain"`, `"scramSha256"`, `"scramSha512"`, and `"gssapi"`. +description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) 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](https://tools.ietf.org/html/rfc7235#user-content-section-5.1). +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](#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 an absolute URL. +scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Security Scheme Object Example + +###### User/Password Authentication Sample + +```json +{ + "type": "userPassword" +} +``` + +```yaml +type: userPassword +``` + +###### API Key Authentication Sample + +```json +{ + "type": "apiKey", + "in": "user" +} +``` + +```yaml +type: apiKey +in: user +``` + +###### X.509 Authentication Sample + +```json +{ + "type": "X509" +} +``` + +```yaml +type: X509 +``` + +###### End-to-end Encryption Authentication Sample + +```json +{ + "type": "symmetricEncryption" +} +``` + +```yaml +type: symmetricEncryption +``` + +###### Basic Authentication Sample + +```json +{ + "type": "http", + "scheme": "basic" +} +``` + +```yaml +type: http +scheme: basic +``` + +###### API Key Sample + +```json +{ + "type": "httpApiKey", + "name": "api_key", + "in": "header" +} +``` + +```yaml +type: httpApiKey +name: api_key +in: header +``` + +###### JWT Bearer Sample + +```json +{ + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT" +} +``` + +```yaml +type: http +scheme: bearer +bearerFormat: JWT +``` + +###### Implicit OAuth2 Sample + +```json +{ + "type": "oauth2", + "flows": { + "implicit": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } + }, + "scopes": [ + "write:pets" + ] +} +``` + +```yaml +type: oauth2 +flows: + implicit: + authorizationUrl: https://example.com/api/oauth/dialog + availableScopes: + write:pets: modify pets in your account + read:pets: read your pets +scopes: + - 'write:pets' +``` + +###### SASL Sample + +```json +{ + "type": "scramSha512" +} +``` + +```yaml +type: scramSha512 +``` + +#### OAuth Flows Object + +Allows configuration of the supported OAuth Flows. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +implicit| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Implicit flow. +password| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Resource Owner Protected Credentials flow. +clientCredentials| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. +authorizationCode| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. + +This object MAY be extended with [Specification Extensions](#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 an absolute URL. +tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. +refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. +availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### OAuth Flow Object Examples + +```JSON +{ + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } +} +``` + +```YAML +authorizationUrl: https://example.com/api/oauth/dialog +tokenUrl: https://example.com/api/oauth/token +availableScopes: + write:pets: modify pets in your account + read:pets: read your pets +``` + + + +### 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](#runtime-expression) is used. + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- +description | `string` | An optional description of the identifier. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +location | `string` | **REQUIRED.** A [runtime expression](#runtime-expression) that specifies the location of the correlation ID. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Examples + +```json +{ + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" +} +``` + +```yaml +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](#user-content-correlationIdObject) and [Operation Reply Address Object](#operation-reply-address-object). + +The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) 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. + +### Traits Merge Mechanism + +Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the target object. + +#### Example + +An object like the following: + +```yaml +description: A longer description. +traits: + - name: UserSignup + description: Description from trait. + - tags: + - name: user +``` + +Would look like the following after applying traits: + +```yaml +name: UserSignup +description: A longer description. +tags: + - name: user +``` + +### 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`](#data-type-formats) | 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](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) +dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) +password | `string` | `password` | Used to hint UIs the input needs to be obscured. From 7e6580f34b1277110d1a02076cd22c24b7a53814 Mon Sep 17 00:00:00 2001 From: artellador <34487006+artellador@users.noreply.github.com> Date: Sat, 24 Feb 2024 17:46:40 +0100 Subject: [PATCH 05/15] Removed unnecesary files --- spec/Fixmd.class | Bin 5051 -> 0 bytes spec/Fixmd.java | 63 -- spec/result.md | 2678 ---------------------------------------------- 3 files changed, 2741 deletions(-) delete mode 100644 spec/Fixmd.class delete mode 100644 spec/Fixmd.java delete mode 100644 spec/result.md diff --git a/spec/Fixmd.class b/spec/Fixmd.class deleted file mode 100644 index fbc04d91831914d9997a41a56bbfeb5ee5097a79..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 5051 zcmcIo33wFc8GirGF`LaO$s$UMLJR?t-5d&vzyc-2M59SSHiCgwJ8UM&!tTsEJ4;9p zZAE+EC)oS6hi#FzYm$n!cWbftU3=g6eOXKU{
Check out the [supported schema formats table](#user-content-multiFormatSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#user-content-multiFormatSchemaFormatTable).
When using [Reference Objects](#reference-object) within the schema, the `schemaFormat` of the referenced resource MUST match the `schemaFormat` of the schema containing the reference. -schema | `any` | **Required**. Definition of the message payload. It can be of any type but defaults to [Schema Object](#user-content-schemaObject). It MUST match the schema format defined in [`schemaFormat`](#user-content-multiFormatSchemaObjectSchemaFormat), including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Schema formats table - -The following table contains a set of values that every implementation MUST support. - -Name | Allowed values | Notes ----|:---:|--- -[AsyncAPI 3.0.0 Schema Object](#schema-object) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided. -[JSON Schema Draft 07](https://json-schema.org/specification-links.html#user-content-draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | - -The following table contains a set of values that every implementation is RECOMMENDED to support. - -Name | Allowed values | Notes ----|:---:|--- -[Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#user-content-schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` | -[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#user-content-schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | -[RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` | -[Protocol Buffers](https://protobuf.dev/) | `application/vnd.google.protobuf;version=2`, `application/vnd.google.protobuf;version=3` | - - -#### Schema Object - -The Schema Object allows the definition of input and output data types. -These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/). The empty schema (which allows any instance to validate) MAY be represented by the `boolean` value `true` and a schema which allows no instance to validate MAY be represented by the `boolean` value `false`. - -Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-handrews-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01). -Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. For other formats (e.g., Avro, RAML, etc) see [Multi Format Schema Object](#multiFormatSchemaObject). - -##### Properties - -The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such, any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to: - -- title -- type -- required -- multipleOf -- maximum -- exclusiveMaximum -- minimum -- exclusiveMinimum -- maxLength -- minLength -- pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#user-content-sec-7.8.5) dialect) -- maxItems -- minItems -- uniqueItems -- maxProperties -- minProperties -- enum -- const -- examples -- if / then / else -- readOnly -- writeOnly -- properties -- patternProperties -- additionalProperties -- additionalItems -- items -- propertyNames -- contains -- allOf -- oneOf -- anyOf -- not - -The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. - -- description - [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -- format - See [Data Type Formats](#data-type-formats) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. -- default - Use it to specify that property has a predefined value if no other value is present. 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](#reference-object) can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the `$ref` keyword MUST follow the behavior described by [Reference Object](#reference-object) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#user-content-ref). - -In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#composition-and-inheritance-(polymorphism)) for more details. -externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this schema. - deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. - -This object MAY be extended with [Specification Extensions](#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 two ways to define the value of a discriminator for an inheriting instance. - -- Use the schema's name. -- Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. - -As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. - -##### Schema Object Examples - -###### Primitive Sample - -```json -{ - "type": "string", - "format": "email" -} -``` - -```yaml -type: string -format: email -``` - -###### Simple Model - -```json -{ - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "age": { - "type": "integer", - "format": "int32", - "minimum": 0 - } - } -} -``` - -```yaml -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: - -```json -{ - "type": "object", - "additionalProperties": { - "type": "string" - } -} -``` - -```yaml -type: object -additionalProperties: - type: string -``` - -For a string to model mapping: - -```json -{ - "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/ComplexModel" - } -} -``` - -```yaml -type: object -additionalProperties: - $ref: '#/components/schemas/ComplexModel' -``` - -###### Model with Example - -```json -{ - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - }, - "required": [ - "name" - ], - "examples": [ - { - "name": "Puma", - "id": 1 - } - ] -} -``` - -```yaml -type: object -properties: - id: - type: integer - format: int64 - name: - type: string -required: -- name -examples: -- name: Puma - id: 1 -``` - -###### Model with Boolean Schemas - -```json -{ - "type": "object", - "required": [ - "anySchema" - ], - "properties": { - "anySchema": true, - "cannotBeDefined": false - } -} -``` - -```yaml -type: object -required: -- anySchema -properties: - anySchema: true - cannotBeDefined: false -``` - -###### Models with Composition - -```json -{ - "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" - } - } - } - ] - } - } -} -``` - -```yaml -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 - -```json -{ - "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" - ] - } - ] - }, - "StickInsect": { - "description": "A representation of an Australian walking stick. Note that `StickBug` will be used as the discriminator value.", - "allOf": [ - { - "$ref": "#/components/schemas/Pet" - }, - { - "type": "object", - "properties": { - "petType": { - "const": "StickBug" - }, - "color": { - "type": "string" - } - }, - "required": [ - "color" - ] - } - ] - } - } -} -``` - -```yaml -schemas: - Pet: - type: object - discriminator: petType - properties: - name: - type: string - petType: - type: string - required: - - name - - petType - ## applies to instances with `petType: "Cat"` - ## because that is the schema name - Cat: - 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 - ## applies to instances with `petType: "Dog"` - ## because that is the schema name - Dog: - 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 - ## applies to instances with `petType: "StickBug"` - ## because that is the required value of the discriminator field, - ## overriding the schema name - StickInsect: - description: A representation of an Australian walking stick - allOf: - - $ref: '#/components/schemas/Pet' - - type: object - properties: - petType: - const: StickBug - color: - type: string - required: - - color -``` - - - - - -#### Security Scheme Object - -Defines a security scheme that can be used by the operations. Supported schemes are: - -* User/Password. -* API key (either as user or as password). -* X.509 certificate. -* End-to-end encryption (either symmetric or asymmetric). -* HTTP authentication. -* HTTP API key. -* OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749). -* [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). -* SASL (Simple Authentication and Security Layer) as defined in [RFC4422](https://tools.ietf.org/html/rfc4422). - -##### 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"`, `"oauth2"`, `"openIdConnect"`, `"plain"`, `"scramSha256"`, `"scramSha512"`, and `"gssapi"`. -description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) 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](https://tools.ietf.org/html/rfc7235#user-content-section-5.1). -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](#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 an absolute URL. -scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Security Scheme Object Example - -###### User/Password Authentication Sample - -```json -{ - "type": "userPassword" -} -``` - -```yaml -type: userPassword -``` - -###### API Key Authentication Sample - -```json -{ - "type": "apiKey", - "in": "user" -} -``` - -```yaml -type: apiKey -in: user -``` - -###### X.509 Authentication Sample - -```json -{ - "type": "X509" -} -``` - -```yaml -type: X509 -``` - -###### End-to-end Encryption Authentication Sample - -```json -{ - "type": "symmetricEncryption" -} -``` - -```yaml -type: symmetricEncryption -``` - -###### Basic Authentication Sample - -```json -{ - "type": "http", - "scheme": "basic" -} -``` - -```yaml -type: http -scheme: basic -``` - -###### API Key Sample - -```json -{ - "type": "httpApiKey", - "name": "api_key", - "in": "header" -} -``` - -```yaml -type: httpApiKey -name: api_key -in: header -``` - -###### JWT Bearer Sample - -```json -{ - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT" -} -``` - -```yaml -type: http -scheme: bearer -bearerFormat: JWT -``` - -###### Implicit OAuth2 Sample - -```json -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "availableScopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - }, - "scopes": [ - "write:pets" - ] -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - availableScopes: - write:pets: modify pets in your account - read:pets: read your pets -scopes: - - 'write:pets' -``` - -###### SASL Sample - -```json -{ - "type": "scramSha512" -} -``` - -```yaml -type: scramSha512 -``` - -#### OAuth Flows Object - -Allows configuration of the supported OAuth Flows. - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -implicit| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Implicit flow. -password| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Resource Owner Protected Credentials flow. -clientCredentials| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. -authorizationCode| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. - -This object MAY be extended with [Specification Extensions](#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 an absolute URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. -availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### OAuth Flow Object Examples - -```JSON -{ - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "availableScopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } -} -``` - -```YAML -authorizationUrl: https://example.com/api/oauth/dialog -tokenUrl: https://example.com/api/oauth/token -availableScopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - - - -### 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](#runtime-expression) is used. - -##### Fixed Fields - -Field Name | Type | Description ----|:---|--- -description | `string` | An optional description of the identifier. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -location | `string` | **REQUIRED.** A [runtime expression](#runtime-expression) that specifies the location of the correlation ID. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Examples - -```json -{ - "description": "Default Correlation ID", - "location": "$message.header#/correlationId" -} -``` - -```yaml -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](#user-content-correlationIdObject) and [Operation Reply Address Object](#operation-reply-address-object). - -The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) 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. - -### Traits Merge Mechanism - -Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the target object. - -#### Example - -An object like the following: - -```yaml -description: A longer description. -traits: - - name: UserSignup - description: Description from trait. - - tags: - - name: user -``` - -Would look like the following after applying traits: - -```yaml -name: UserSignup -description: A longer description. -tags: - - name: user -``` - -### 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`](#data-type-formats) | 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](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) -dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) -password | `string` | `password` | Used to hint UIs the input needs to be obscured. From 20274137cebdc6c4e202be8243d97138c0b78e1f Mon Sep 17 00:00:00 2001 From: artellador <34487006+artellador@users.noreply.github.com> Date: Sat, 24 Feb 2024 17:47:45 +0100 Subject: [PATCH 06/15] Delete .Fixmd.java.swp --- spec/.Fixmd.java.swp | Bin 1024 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 spec/.Fixmd.java.swp diff --git a/spec/.Fixmd.java.swp b/spec/.Fixmd.java.swp deleted file mode 100644 index 06b6af98f329c170eb4d79936c1b5b42fb92b0d0..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1024 zcmYc?$V<%2S1{8vVn6}$>
Check out the [supported schema formats table](#user-content-multiFormatSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#user-content-multiFormatSchemaFormatTable).
When using [Reference Objects](#reference-object) within the schema, the `schemaFormat` of the referenced resource MUST match the `schemaFormat` of the schema containing the reference. +schema | `any` | **Required**. Definition of the message payload. It can be of any type but defaults to [Schema Object](#user-content-schemaObject). It MUST match the schema format defined in [`schemaFormat`](#user-content-multiFormatSchemaObjectSchemaFormat), including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Schema formats table + +The following table contains a set of values that every implementation MUST support. + +Name | Allowed values | Notes +---|:---:|--- +[AsyncAPI 3.0.0 Schema Object](#schema-object) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided. +[JSON Schema Draft 07](https://json-schema.org/specification-links.html#user-content-draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | + +The following table contains a set of values that every implementation is RECOMMENDED to support. + +Name | Allowed values | Notes +---|:---:|--- +[Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#user-content-schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` | +[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#user-content-schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | +[RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` | +[Protocol Buffers](https://protobuf.dev/) | `application/vnd.google.protobuf;version=2`, `application/vnd.google.protobuf;version=3` | + + +#### Schema Object + +The Schema Object allows the definition of input and output data types. +These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/). The empty schema (which allows any instance to validate) MAY be represented by the `boolean` value `true` and a schema which allows no instance to validate MAY be represented by the `boolean` value `false`. + +Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-handrews-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01). +Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. For other formats (e.g., Avro, RAML, etc) see [Multi Format Schema Object](#multiFormatSchemaObject). + +##### Properties + +The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such, any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to: + +- title +- type +- required +- multipleOf +- maximum +- exclusiveMaximum +- minimum +- exclusiveMinimum +- maxLength +- minLength +- pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#user-content-sec-7.8.5) dialect) +- maxItems +- minItems +- uniqueItems +- maxProperties +- minProperties +- enum +- const +- examples +- if / then / else +- readOnly +- writeOnly +- properties +- patternProperties +- additionalProperties +- additionalItems +- items +- propertyNames +- contains +- allOf +- oneOf +- anyOf +- not + +The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. + +- description - [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +- format - See [Data Type Formats](#data-type-formats) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. +- default - Use it to specify that property has a predefined value if no other value is present. 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](#reference-object) can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the `$ref` keyword MUST follow the behavior described by [Reference Object](#reference-object) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#user-content-ref). + +In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#composition-and-inheritance-(polymorphism)) for more details. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this schema. + deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. + +This object MAY be extended with [Specification Extensions](#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 two ways to define the value of a discriminator for an inheriting instance. + +- Use the schema's name. +- Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. + +As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. + +##### Schema Object Examples + +###### Primitive Sample + +```json +{ + "type": "string", + "format": "email" +} +``` + +```yaml +type: string +format: email +``` + +###### Simple Model + +```json +{ + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "address": { + "$ref": "#/components/schemas/Address" + }, + "age": { + "type": "integer", + "format": "int32", + "minimum": 0 + } + } +} +``` + +```yaml +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: + +```json +{ + "type": "object", + "additionalProperties": { + "type": "string" + } +} +``` + +```yaml +type: object +additionalProperties: + type: string +``` + +For a string to model mapping: + +```json +{ + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/ComplexModel" + } +} +``` + +```yaml +type: object +additionalProperties: + $ref: '#/components/schemas/ComplexModel' +``` + +###### Model with Example + +```json +{ + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "examples": [ + { + "name": "Puma", + "id": 1 + } + ] +} +``` + +```yaml +type: object +properties: + id: + type: integer + format: int64 + name: + type: string +required: +- name +examples: +- name: Puma + id: 1 +``` + +###### Model with Boolean Schemas + +```json +{ + "type": "object", + "required": [ + "anySchema" + ], + "properties": { + "anySchema": true, + "cannotBeDefined": false + } +} +``` + +```yaml +type: object +required: +- anySchema +properties: + anySchema: true + cannotBeDefined: false +``` + +###### Models with Composition + +```json +{ + "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" + } + } + } + ] + } + } +} +``` + +```yaml +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 + +```json +{ + "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" + ] + } + ] + }, + "StickInsect": { + "description": "A representation of an Australian walking stick. Note that `StickBug` will be used as the discriminator value.", + "allOf": [ + { + "$ref": "#/components/schemas/Pet" + }, + { + "type": "object", + "properties": { + "petType": { + "const": "StickBug" + }, + "color": { + "type": "string" + } + }, + "required": [ + "color" + ] + } + ] + } + } +} +``` + +```yaml +schemas: + Pet: + type: object + discriminator: petType + properties: + name: + type: string + petType: + type: string + required: + - name + - petType + ## applies to instances with `petType: "Cat"` + ## because that is the schema name + Cat: + 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 + ## applies to instances with `petType: "Dog"` + ## because that is the schema name + Dog: + 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 + ## applies to instances with `petType: "StickBug"` + ## because that is the required value of the discriminator field, + ## overriding the schema name + StickInsect: + description: A representation of an Australian walking stick + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + properties: + petType: + const: StickBug + color: + type: string + required: + - color +``` + + + + + +#### Security Scheme Object + +Defines a security scheme that can be used by the operations. Supported schemes are: + +* User/Password. +* API key (either as user or as password). +* X.509 certificate. +* End-to-end encryption (either symmetric or asymmetric). +* HTTP authentication. +* HTTP API key. +* OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749). +* [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). +* SASL (Simple Authentication and Security Layer) as defined in [RFC4422](https://tools.ietf.org/html/rfc4422). + +##### 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"`, `"oauth2"`, `"openIdConnect"`, `"plain"`, `"scramSha256"`, `"scramSha512"`, and `"gssapi"`. +description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) 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](https://tools.ietf.org/html/rfc7235#user-content-section-5.1). +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](#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 an absolute URL. +scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Security Scheme Object Example + +###### User/Password Authentication Sample + +```json +{ + "type": "userPassword" +} +``` + +```yaml +type: userPassword +``` + +###### API Key Authentication Sample + +```json +{ + "type": "apiKey", + "in": "user" +} +``` + +```yaml +type: apiKey +in: user +``` + +###### X.509 Authentication Sample + +```json +{ + "type": "X509" +} +``` + +```yaml +type: X509 +``` + +###### End-to-end Encryption Authentication Sample + +```json +{ + "type": "symmetricEncryption" +} +``` + +```yaml +type: symmetricEncryption +``` + +###### Basic Authentication Sample + +```json +{ + "type": "http", + "scheme": "basic" +} +``` + +```yaml +type: http +scheme: basic +``` + +###### API Key Sample + +```json +{ + "type": "httpApiKey", + "name": "api_key", + "in": "header" +} +``` + +```yaml +type: httpApiKey +name: api_key +in: header +``` + +###### JWT Bearer Sample + +```json +{ + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT" +} +``` + +```yaml +type: http +scheme: bearer +bearerFormat: JWT +``` + +###### Implicit OAuth2 Sample + +```json +{ + "type": "oauth2", + "flows": { + "implicit": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } + }, + "scopes": [ + "write:pets" + ] +} +``` + +```yaml +type: oauth2 +flows: + implicit: + authorizationUrl: https://example.com/api/oauth/dialog + availableScopes: + write:pets: modify pets in your account + read:pets: read your pets +scopes: + - 'write:pets' +``` + +###### SASL Sample + +```json +{ + "type": "scramSha512" +} +``` + +```yaml +type: scramSha512 +``` + +#### OAuth Flows Object + +Allows configuration of the supported OAuth Flows. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +implicit| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Implicit flow. +password| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Resource Owner Protected Credentials flow. +clientCredentials| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. +authorizationCode| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. + +This object MAY be extended with [Specification Extensions](#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 an absolute URL. +tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. +refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. +availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### OAuth Flow Object Examples + +```JSON +{ + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } +} +``` + +```YAML +authorizationUrl: https://example.com/api/oauth/dialog +tokenUrl: https://example.com/api/oauth/token +availableScopes: + write:pets: modify pets in your account + read:pets: read your pets +``` + + + +### 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](#runtime-expression) is used. + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- +description | `string` | An optional description of the identifier. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +location | `string` | **REQUIRED.** A [runtime expression](#runtime-expression) that specifies the location of the correlation ID. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Examples + +```json +{ + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" +} +``` + +```yaml +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](#user-content-correlationIdObject) and [Operation Reply Address Object](#operation-reply-address-object). + +The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) 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. + +### Traits Merge Mechanism + +Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the target object. + +#### Example + +An object like the following: + +```yaml +description: A longer description. +traits: + - name: UserSignup + description: Description from trait. + - tags: + - name: user +``` + +Would look like the following after applying traits: + +```yaml +name: UserSignup +description: A longer description. +tags: + - name: user +``` + +### 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`](#data-type-formats) | 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](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) +dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) +password | `string` | `password` | Used to hint UIs the input needs to be obscured. From 33c260f243dd48f4b5d7160211f8f1ca9ca2eb98 Mon Sep 17 00:00:00 2001 From: artellando
Check out the [supported schema formats table](#user-content-multiFormatSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#user-content-multiFormatSchemaFormatTable).
When using [Reference Objects](#reference-object) within the schema, the `schemaFormat` of the referenced resource MUST match the `schemaFormat` of the schema containing the reference. -schema | `any` | **Required**. Definition of the message payload. It can be of any type but defaults to [Schema Object](#user-content-schemaObject). It MUST match the schema format defined in [`schemaFormat`](#user-content-multiFormatSchemaObjectSchemaFormat), including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Schema formats table - -The following table contains a set of values that every implementation MUST support. - -Name | Allowed values | Notes ----|:---:|--- -[AsyncAPI 3.0.0 Schema Object](#schema-object) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided. -[JSON Schema Draft 07](https://json-schema.org/specification-links.html#user-content-draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | - -The following table contains a set of values that every implementation is RECOMMENDED to support. - -Name | Allowed values | Notes ----|:---:|--- -[Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#user-content-schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` | -[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#user-content-schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | -[RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` | -[Protocol Buffers](https://protobuf.dev/) | `application/vnd.google.protobuf;version=2`, `application/vnd.google.protobuf;version=3` | - - -#### Schema Object - -The Schema Object allows the definition of input and output data types. -These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/). The empty schema (which allows any instance to validate) MAY be represented by the `boolean` value `true` and a schema which allows no instance to validate MAY be represented by the `boolean` value `false`. - -Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-handrews-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01). -Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. For other formats (e.g., Avro, RAML, etc) see [Multi Format Schema Object](#multiFormatSchemaObject). - -##### Properties - -The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such, any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to: - -- title -- type -- required -- multipleOf -- maximum -- exclusiveMaximum -- minimum -- exclusiveMinimum -- maxLength -- minLength -- pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#user-content-sec-7.8.5) dialect) -- maxItems -- minItems -- uniqueItems -- maxProperties -- minProperties -- enum -- const -- examples -- if / then / else -- readOnly -- writeOnly -- properties -- patternProperties -- additionalProperties -- additionalItems -- items -- propertyNames -- contains -- allOf -- oneOf -- anyOf -- not - -The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. - -- description - [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -- format - See [Data Type Formats](#data-type-formats) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. -- default - Use it to specify that property has a predefined value if no other value is present. 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](#reference-object) can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the `$ref` keyword MUST follow the behavior described by [Reference Object](#reference-object) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#user-content-ref). - -In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#composition-and-inheritance-(polymorphism)) for more details. -externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this schema. - deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. - -This object MAY be extended with [Specification Extensions](#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 two ways to define the value of a discriminator for an inheriting instance. - -- Use the schema's name. -- Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. - -As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. - -##### Schema Object Examples - -###### Primitive Sample - -```json -{ - "type": "string", - "format": "email" -} -``` - -```yaml -type: string -format: email -``` - -###### Simple Model - -```json -{ - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "age": { - "type": "integer", - "format": "int32", - "minimum": 0 - } - } -} -``` - -```yaml -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: - -```json -{ - "type": "object", - "additionalProperties": { - "type": "string" - } -} -``` - -```yaml -type: object -additionalProperties: - type: string -``` - -For a string to model mapping: - -```json -{ - "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/ComplexModel" - } -} -``` - -```yaml -type: object -additionalProperties: - $ref: '#/components/schemas/ComplexModel' -``` - -###### Model with Example - -```json -{ - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - }, - "required": [ - "name" - ], - "examples": [ - { - "name": "Puma", - "id": 1 - } - ] -} -``` - -```yaml -type: object -properties: - id: - type: integer - format: int64 - name: - type: string -required: -- name -examples: -- name: Puma - id: 1 -``` - -###### Model with Boolean Schemas - -```json -{ - "type": "object", - "required": [ - "anySchema" - ], - "properties": { - "anySchema": true, - "cannotBeDefined": false - } -} -``` - -```yaml -type: object -required: -- anySchema -properties: - anySchema: true - cannotBeDefined: false -``` - -###### Models with Composition - -```json -{ - "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" - } - } - } - ] - } - } -} -``` - -```yaml -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 - -```json -{ - "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" - ] - } - ] - }, - "StickInsect": { - "description": "A representation of an Australian walking stick. Note that `StickBug` will be used as the discriminator value.", - "allOf": [ - { - "$ref": "#/components/schemas/Pet" - }, - { - "type": "object", - "properties": { - "petType": { - "const": "StickBug" - }, - "color": { - "type": "string" - } - }, - "required": [ - "color" - ] - } - ] - } - } -} -``` - -```yaml -schemas: - Pet: - type: object - discriminator: petType - properties: - name: - type: string - petType: - type: string - required: - - name - - petType - ## applies to instances with `petType: "Cat"` - ## because that is the schema name - Cat: - 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 - ## applies to instances with `petType: "Dog"` - ## because that is the schema name - Dog: - 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 - ## applies to instances with `petType: "StickBug"` - ## because that is the required value of the discriminator field, - ## overriding the schema name - StickInsect: - description: A representation of an Australian walking stick - allOf: - - $ref: '#/components/schemas/Pet' - - type: object - properties: - petType: - const: StickBug - color: - type: string - required: - - color -``` - - - - - -#### Security Scheme Object - -Defines a security scheme that can be used by the operations. Supported schemes are: - -* User/Password. -* API key (either as user or as password). -* X.509 certificate. -* End-to-end encryption (either symmetric or asymmetric). -* HTTP authentication. -* HTTP API key. -* OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749). -* [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). -* SASL (Simple Authentication and Security Layer) as defined in [RFC4422](https://tools.ietf.org/html/rfc4422). - -##### 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"`, `"oauth2"`, `"openIdConnect"`, `"plain"`, `"scramSha256"`, `"scramSha512"`, and `"gssapi"`. -description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) 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](https://tools.ietf.org/html/rfc7235#user-content-section-5.1). -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](#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 an absolute URL. -scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Security Scheme Object Example - -###### User/Password Authentication Sample - -```json -{ - "type": "userPassword" -} -``` - -```yaml -type: userPassword -``` - -###### API Key Authentication Sample - -```json -{ - "type": "apiKey", - "in": "user" -} -``` - -```yaml -type: apiKey -in: user -``` - -###### X.509 Authentication Sample - -```json -{ - "type": "X509" -} -``` - -```yaml -type: X509 -``` - -###### End-to-end Encryption Authentication Sample - -```json -{ - "type": "symmetricEncryption" -} -``` - -```yaml -type: symmetricEncryption -``` - -###### Basic Authentication Sample - -```json -{ - "type": "http", - "scheme": "basic" -} -``` - -```yaml -type: http -scheme: basic -``` - -###### API Key Sample - -```json -{ - "type": "httpApiKey", - "name": "api_key", - "in": "header" -} -``` - -```yaml -type: httpApiKey -name: api_key -in: header -``` - -###### JWT Bearer Sample - -```json -{ - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT" -} -``` - -```yaml -type: http -scheme: bearer -bearerFormat: JWT -``` - -###### Implicit OAuth2 Sample - -```json -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "availableScopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - }, - "scopes": [ - "write:pets" - ] -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - availableScopes: - write:pets: modify pets in your account - read:pets: read your pets -scopes: - - 'write:pets' -``` - -###### SASL Sample - -```json -{ - "type": "scramSha512" -} -``` - -```yaml -type: scramSha512 -``` - -#### OAuth Flows Object - -Allows configuration of the supported OAuth Flows. - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -implicit| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Implicit flow. -password| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Resource Owner Protected Credentials flow. -clientCredentials| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. -authorizationCode| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. - -This object MAY be extended with [Specification Extensions](#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 an absolute URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. -availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### OAuth Flow Object Examples - -```JSON -{ - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "availableScopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } -} -``` - -```YAML -authorizationUrl: https://example.com/api/oauth/dialog -tokenUrl: https://example.com/api/oauth/token -availableScopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - - - -### 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](#runtime-expression) is used. - -##### Fixed Fields - -Field Name | Type | Description ----|:---|--- -description | `string` | An optional description of the identifier. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -location | `string` | **REQUIRED.** A [runtime expression](#runtime-expression) that specifies the location of the correlation ID. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Examples - -```json -{ - "description": "Default Correlation ID", - "location": "$message.header#/correlationId" -} -``` - -```yaml -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](#user-content-correlationIdObject) and [Operation Reply Address Object](#operation-reply-address-object). - -The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) 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. - -### Traits Merge Mechanism - -Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the target object. - -#### Example - -An object like the following: - -```yaml -description: A longer description. -traits: - - name: UserSignup - description: Description from trait. - - tags: - - name: user -``` - -Would look like the following after applying traits: - -```yaml -name: UserSignup -description: A longer description. -tags: - - name: user -``` - -### 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`](#data-type-formats) | 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](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) -dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) -password | `string` | `password` | Used to hint UIs the input needs to be obscured. +# AsyncAPI Specification + +#### Attribution + +Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). + +#### Version 3.0.0 + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). + +The AsyncAPI Specification is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). + +## Introduction + +The AsyncAPI Specification is a project used to describe message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). + +The AsyncAPI Specification defines a set of fields that can be used in an AsyncAPI document to describe an [application](#application)'s API. The document may reference other files for additional details or shared fields, but it is typically a single, primary document that encapsulates the API description. + +The AsyncAPI document SHOULD describe the operations an [application](#application) performs. For instance, consider the following AsyncAPI definition snippet: + +```yaml +channels: + userSignedUp: + # ...(redacted for brevity) +operations: + onUserSignedUp: + action: receive + channel: + $ref: "#/channels/userSignedUp" +``` + +It means that the [application](#user-content-definitionsApplication) will receive messages from the `userSignedUp` [channel](#channel). + +**The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol. + +It's NOT RECOMMENDED to derive a [receiver](#user-content-definitionsReceiver) AsyncAPI document from a [sender](#sender) one or vice versa. There are no guarantees that the channel used by an application to receive messages will be the same channel where another application is sending them. Also, certain fields in the document like `summary`, `description`, and the id of the operation might stop making sense. For instance, given the following receiver snippet: + +```yaml +operations: + onUserSignedUp: + summary: On user signed up. + description: Event received when a user signed up on the product. + action: receive + channel: + $ref: "#/channels/userSignedUp" +``` + +We can't automatically assume that an _opposite_ application exists by simply replacing `receive` with `send`: + +```yaml +operations: + onUserSignedUp: # <-- This doesn't make sense now. Should be something like sendUserSignedUp. + summary: On user signed up. # <-- This doesn't make sense now. Should say something like "Sends a user signed up event". + description: Event received when a user signed up on the product. # <-- This doesn't make sense now. Should speak about sending an event, not receiving it. + action: send + channel: + $ref: "#/channels/userSignedUp" +``` + +Aside from the issues mentioned above, there may also be infrastructure configuration that is not represented here. For instance, a system may use a read-only channel for receiving messages, a different one for sending them, and an intermediary process that will forward messages from one channel to the other. + +## Table of Contents + + +- [Definitions](#definitions) + - [Server](#server) + - [Application](#application) + - [Sender](#sender) + - [Receiver](#receiver) + - [Message](#message) + - [Channel](#channel) + - [Protocol](#protocol) +- [Specification](#specification) + - [Format](#format) + - [File Structure](#file-structure) + - [Absolute URLs](#absolute-urls) + - [Schema](#schema) + - [AsyncAPI Object](#asyncapi-object) + - [AsyncAPI Version String](#asyncapi-version-string) + - [Identifier](#identifier) + - [Info Object](#info-object) + - [Contact Object](#contact-object) + - [License Object](#license-object) + - [Servers Object](#servers-object) + - [Server Object](#server-object) + - [Server Variable Object](#server-variable-object) + - [Default Content Type](#default-content-type) + - [Channels Object](#channels-object) + - [Channel Object](#channel-object) + - [Operations Object](#operations-object) + - [Operation Object](#operation-object) + - [Operation Trait Object](#operation-trait-object) + - [Operation Reply Object](#operation-reply-object) + - [Operation Reply Address Object](#operation-reply-address-object) + - [Message Object](#message-object) + - [Message Trait Object](#message-trait-object) + - [Message Example Object](#message-example-object) + - [Tags Object](#tags-object) + - [Tag Object](#user-content-tag-object) + - [External Documentation Object](#external-documentation-object) + - [Components Object](#components-object) + - [Reference Object](#reference-object) + - [Multi Format Schema Object](#multi-format-schema-object) + - [Schema Object](#schema-object) + - [Security Scheme Object](#security-scheme-object) + - [OAuth Flows Object](#user-content-oauth-flows-object) + - [OAuth Flow Object](#user-content-oauth-flow-object) + - [Server Bindings Object](#server-bindings-object) + - [Parameters Object](#parameters-object) + - [Parameter Object](#parameter-object) + - [Channel Bindings Object](#channel-bindings-object) + - [Operation Bindings Object](#operation-bindings-object) + - [Message Bindings Object](#message-bindings-object) + - [Correlation ID Object](#correlation-id-object) + - [Specification Extensions](#specification-extensions) + + + +## Definitions + +### Server +A server MAY be a message broker that is capable of sending and/or receiving between a [sender](#user-content-definitionsSender) and [receiver](#receiver). A server MAY be a service with WebSocket API that enables message-driven communication between browser-to-server or server-to-server. + +### Application +An application is any kind of computer program or a group of them. It MUST be a [sender](#user-content-definitionsSender), a [receiver](#user-content-definitionsReceiver), or both. An application MAY be a microservice, IoT device (sensor), mainframe process, message broker, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#user-content-definitionsProtocol). An application MUST also use a protocol supported by the [server](#user-content-definitionsServer) in order to connect and exchange [messages](#message). + +### Sender +A sender is a type of application, that is sending [messages](#user-content-definitionsMessage) to [channels](#user-content-definitionsChannel). A sender MAY send to multiple channels depending on the [server](#server), protocol, and use-case pattern. + +### Receiver +A receiver is a type of application that is receiving [messages](#user-content-definitionsMessage) from [channels](#user-content-definitionsChannel). A receiver MAY receive from multiple channels depending on the [server](#server), protocol, and the use-case pattern. A receiver MAY forward a received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and forwards them. + +### Message +A message is the mechanism by which information is exchanged via a channel between [servers](#user-content-definitionsServer) and applications. A message MAY contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#protocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. + +### Channel +A channel is an addressable component, made available by the [server](#server), for the organization of [messages](#user-content-definitionsMessage). [Sender](#user-content-definitionsSender) applications send messages to channels and [receiver](#user-content-definitionsReceiver) applications receive messages from channels. [Servers](#server) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#server) implementation, the channel MAY be included in the message via protocol-defined headers. + +### Protocol +A protocol is the mechanism (wireline protocol or API) by which [messages](#user-content-definitionsMessage) are exchanged between the application and the [channel](#channel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket, Google Pub/Sub, Pulsar. + +### Bindings +A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only. + +## Specification + +### Format + +The files describing the message-driven API in accordance with the AsyncAPI Specification are represented as JSON objects and conform to the JSON standards. +YAML, being a superset of JSON, can be used as well to represent a A2S (AsyncAPI Specification) file. + +For example, if a field is said to have an array value, the JSON array representation will be used: + +```yaml +{ + "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](https://www.yaml.org/spec/1.2/spec.html) is recommended along with some additional constraints: + +- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://www.yaml.org/spec/1.2/spec.html#user-content-id2803231) +- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset + +### File Structure + +An AsyncAPI document MAY be made up of a single document or be divided into multiple, +connected parts at the discretion of the author. In the latter case, [Reference Objects](#reference-object) are used. + +It is important to note that everything that is defined in an AsyncAPI document MUST be used by the implemented [Application](#application), with the exception of the [Components Object](#user-content-componentsObject). Everything that is defined inside the Components Object represents a resource that MAY or MAY NOT be used by the implemented [Application](#application). + +By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. + +### Absolute URLs + +Unless specified otherwise, all properties that are absolute URLs are defined by [RFC3986, section 4.3](https://datatracker.ietf.org/doc/html/rfc3986#user-content-section-4.3). + +### Schema + +#### AsyncAPI Object + +This is the root document object for the API specification. +It combines resource listing and API declaration together into one document. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +asyncapi | [AsyncAPI Version String](#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](#user-content-A2SIdString) | Identifier of the [application](#application) the AsyncAPI document is defining. +info | [Info Object](#info-object) | **REQUIRED.** Provides metadata about the API. The metadata can be used by the clients if needed. +servers | [Servers Object](#servers-object) | Provides connection details of servers. +defaultContentType | [Default Content Type](#default-content-type) | Default content type to use when encoding/decoding a message's payload. +channels | [Channels Object](#user-content-channelsObject) | The channels used by this [application](#application). +operations | [Operations Object](#user-content-operationsObject) | The operations this [application](#application) MUST implement. +components | [Components Object](#user-content-componentsObject) | An element to hold various reusable objects for the specification. Everything that is defined inside this object represents a resource that MAY or MAY NOT be used in the rest of the document and MAY or MAY NOT be used by the implemented [Application](#application). + +This object MAY be extended with [Specification Extensions](#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](#application) the AsyncAPI document is defining. It must conform to the URI format, according to [RFC3986](https://tools.ietf.org/html/rfc3986). + +It is RECOMMENDED to use a [URN](https://tools.ietf.org/html/rfc8141) to globally and uniquely identify the application during long periods of time, even after it becomes unavailable or ceases to exist. + +###### Examples + +```json +{ + "id": "urn:example:com:smartylighting:streetlights:server" +} +``` + +```yaml +id: 'urn:example:com:smartylighting:streetlights:server' +``` + +```json +{ + "id": "https://github.com/smartylighting/streetlights-server" +} +``` + +```yaml +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](https://spec.commonmark.org/) can be used for rich text representation. +termsOfService | `string` | A URL to the Terms of Service for the API. This MUST be in the form of an absolute URL. +contact | [Contact Object](#contact-object) | The contact information for the exposed API. +license | [License Object](#license-object) | The license information for the exposed API. +tags | [Tags Object](#tags-object) | A list of tags for application API documentation control. Tags can be used for logical grouping of applications. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation of the exposed API. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Info Object Example: + +```json +{ + "title": "AsyncAPI Sample App", + "version": "1.0.1", + "description": "This is a sample app.", + "termsOfService": "https://asyncapi.org/terms/", + "contact": { + "name": "API Support", + "url": "https://www.asyncapi.org/support", + "email": "support@asyncapi.org" + }, + "license": { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + }, + "externalDocs": { + "description": "Find more info here", + "url": "https://www.asyncapi.org" + }, + "tags": [ + { + "name": "e-commerce" + } + ] +} +``` + +```yaml +title: AsyncAPI Sample App +version: 1.0.1 +description: This is a sample app. +termsOfService: https://asyncapi.org/terms/ +contact: + name: API Support + url: https://www.asyncapi.org/support + email: support@asyncapi.org +license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html +externalDocs: + description: Find more info here + url: https://www.asyncapi.org +tags: + - name: e-commerce +``` + +#### 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. This MUST be in the form of an absolute URL. +email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Contact Object Example: + +```json +{ + "name": "API Support", + "url": "https://www.example.com/support", + "email": "support@example.com" +} +``` + +```yaml +name: API Support +url: https://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. This MUST be in the form of an absolute URL. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### License Object Example: + +```json +{ + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" +} +``` + +```yaml +name: Apache 2.0 +url: https://www.apache.org/licenses/LICENSE-2.0.html +``` + +#### Servers Object + +The Servers Object is a map of [Server Objects](#server-object). + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +`^[A-Za-z0-9_\-]+$` | [Server Object](#user-content-serverObject) \| [Reference Object](#reference-object) | The definition of a server this application MAY connect to. + +##### Servers Object Example + +```json +{ + "development": { + "host": "localhost:5672", + "description": "Development AMQP broker.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:development", + "description": "This environment is meant for developers to run their own tests." + } + ] + }, + "staging": { + "host": "rabbitmq-staging.in.mycompany.com:5672", + "description": "RabbitMQ broker for the staging environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:staging", + "description": "This environment is a replica of the production environment." + } + ] + }, + "production": { + "host": "rabbitmq.in.mycompany.com:5672", + "description": "RabbitMQ broker for the production environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:production", + "description": "This environment is the live environment available for final users." + } + ] + } +} +``` + +```yaml +development: + host: localhost:5672 + description: Development AMQP broker. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:development" + description: "This environment is meant for developers to run their own tests." +staging: + host: rabbitmq-staging.in.mycompany.com:5672 + description: RabbitMQ broker for the staging environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:staging" + description: "This environment is a replica of the production environment." +production: + host: rabbitmq.in.mycompany.com:5672 + description: RabbitMQ broker for the production environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:production" + description: "This environment is the live environment available for final users." +``` + + +#### Server Object + +An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +host | `string` | **REQUIRED**. The server host name. It MAY include the port. This field supports [Server Variables](#user-content-serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. +protocol | `string` | **REQUIRED**. The protocol this server supports for connection. +protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. +pathname | `string` | The path to a resource in the host. This field supports [Server Variables](#user-content-serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. +description | `string` | An optional string describing the server. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +title | `string` | A human-friendly title for the server. +summary | `string` | A short summary of the server. +variables | Map[`string`, [Server Variable Object](#user-content-serverVariableObject) \| [Reference Object](#reference-object)]] | A map between a variable name and its value. The value is used for substitution in the server's `host` and `pathname` template. +security | [[Security Scheme Object](#security-scheme-object) \| [Reference Object](#user-content-referenceObject)] | A declaration of which security schemes can be used with this server. The list of values includes alternative [security scheme objects](#security-scheme-object) that can be used. Only one of the security scheme objects need to be satisfied to authorize a connection or operation. +tags | [Tags Object](#tags-object) | A list of tags for logical grouping and categorization of servers. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this server. +bindings | [Server Bindings Object](#user-content-serverBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server. + +##### Server Object Example + +A single server would be described as: + +```json +{ + "host": "kafka.in.mycompany.com:9092", + "description": "Production Kafka broker.", + "protocol": "kafka", + "protocolVersion": "3.2" +} +``` + +```yaml +host: kafka.in.mycompany.com:9092 +description: Production Kafka broker. +protocol: kafka +protocolVersion: '3.2' +``` + +An example of a server that has a `pathname`: + +```json +{ + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/production", + "protocol": "amqp", + "description": "Production RabbitMQ broker (uses the `production` vhost)." +} +``` + +```yaml +host: rabbitmq.in.mycompany.com:5672 +pathname: /production +protocol: amqp +description: Production RabbitMQ broker (uses the `production` vhost). +``` + +#### Server Variable Object + +An object representing a Server Variable for server URL template substitution. + +##### 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](https://spec.commonmark.org/) 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](#specification-extensions). + +##### Server Variable Object Example + +```json +{ + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/{env}", + "protocol": "amqp", + "description": "RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`.", + "variables": { + "env": { + "description": "Environment to connect to. It can be either `production` or `staging`.", + "enum": [ + "production", + "staging" + ] + } + } +} +``` + +```yaml +host: 'rabbitmq.in.mycompany.com:5672' +pathname: '/{env}' +protocol: amqp +description: RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`. +variables: + env: + description: Environment to connect to. It can be either `production` or `staging`. + enum: + - production + - staging +``` + + +#### Default Content Type + +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](#user-content-messageObjectContentType) 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 + +```json +{ + "defaultContentType": "application/json" +} +``` + +```yaml +defaultContentType: application/json +``` + + + + + + +#### Channels Object + +An object containing all the [Channel Object](#user-content-channelObject) definitions the [Application](#application) MUST use during runtime. + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +{channelId} | [Channel Object](#user-content-channelObject) \| [Reference Object](#reference-object) | An identifier for the described channel. The `channelId` value is **case-sensitive**. Tools and libraries MAY use the `channelId` to uniquely identify a channel, therefore, it is RECOMMENDED to follow common programming naming conventions. + +##### Channels Object Example + +```json +{ + "userSignedUp": { + "address": "user.signedup", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + } + } + } +} +``` + +```yaml +userSignedUp: + address: 'user.signedup' + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' +``` + + + + +#### Channel Object + +Describes a shared communication channel. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#user-content-channelAddressExpressions). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channel-bindings-object) to define them. +messages | [Messages Object](#user-content-messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#message-object) defined in this map.** +title | `string` | A human-friendly title for the channel. +summary | `string` | A short summary of the channel. +description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +servers | [[Reference Object](#user-content-referenceObject)] | An array of `$ref` pointers to the definition of the servers in which this channel is available. If the channel is located in the [root Channels Object](#user-content-channelsObject), it MUST point to a subset of server definitions located in the [root Servers Object](#user-content-serversObject), and MUST NOT point to a subset of server definitions located in the [Components Object](#user-content-componentsObject) or anywhere else. If the channel is located in the [Components Object](#user-content-componentsObject), it MAY point to a [Server Objects](#server-object) in any location. If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#user-content-serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#user-content-referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#server-object). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +parameters | [Parameters Object](#user-content-parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](#channel-address-expressions). +tags | [Tags Object](#tags-object) | A list of tags for logical grouping of channels. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this channel. +bindings | [Channel Bindings Object](#user-content-channelBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. + + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Channel Object Example + +```json +{ + "address": "users.{userId}", + "title": "Users channel", + "description": "This channel is used to exchange messages about user events.", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" + } + }, + "parameters": { + "userId": { + "$ref": "#/components/parameters/userId" + } + }, + "servers": [ + { "$ref": "#/servers/rabbitmqInProd" }, + { "$ref": "#/servers/rabbitmqInStaging" } + ], + "bindings": { + "amqp": { + "is": "queue", + "queue": { + "exclusive": true + } + } + }, + "tags": [{ + "name": "user", + "description": "User-related messages" + }], + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" + } +} +``` + +```yaml +address: 'users.{userId}' +title: Users channel +description: This channel is used to exchange messages about user events. +messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' +parameters: + userId: + $ref: '#/components/parameters/userId' +servers: + - $ref: '#/servers/rabbitmqInProd' + - $ref: '#/servers/rabbitmqInStaging' +bindings: + amqp: + is: queue + queue: + exclusive: true +tags: + - name: user + description: User-related messages +externalDocs: + description: 'Find more info here' + url: 'https://example.com' +``` + + + + + +#### Channel Address Expressions + +Channel addresses MAY contain expressions that can be used to define dynamic values. + +Expressions MUST be composed by a name enclosed in curly braces (`{` and `}`). E.g., `{userId}`. + + + + + +#### Messages Object + +Describes a map of messages included in a channel. + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +`{messageId}` | [Message Object](#user-content-messageObject) \| [Reference Object](#reference-object) | The key represents the message identifier. The `messageId` value is **case-sensitive**. Tools and libraries MAY use the `messageId` value to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. + +##### Messages Object Example + +```json +{ + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" + } +} +``` + +```yaml +userSignedUp: + $ref: '#/components/messages/userSignedUp' +userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' +``` + + + +#### Operations Object + +Holds a dictionary with all the [operations](#operation-object) this application MUST implement. + +> If you're looking for a place to define operations that MAY or MAY NOT be implemented by the application, consider defining them in [`components/operations`](#user-content-componentsOperations). + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +{operationId} | [Operation Object](#user-content-operationObject) \| [Reference Object](#reference-object) | The operation this application MUST implement. The field name (`operationId`) MUST be a string used to identify the operation in the document where it is defined, and its value is **case-sensitive**. Tools and libraries MAY use the `operationId` to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. + +##### Operations Object Example + +```json +{ + "onUserSignUp": { + "title": "User sign up", + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { "$ref": "#/components/operationTraits/kafka" } + ] + } +} +``` + +```yaml +onUserSignUp: + title: User sign up + summary: Action to sign a user up. + description: A longer description + channel: + $ref: '#/channels/userSignup' + action: send + tags: + - name: user + - name: signup + - name: register + bindings: + amqp: + ack: false + traits: + - $ref: '#/components/operationTraits/kafka' +``` + + +#### Operation Object + +Describes a specific operation. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +action | `"send"` &#user-content-124; `"receive"` | **Required**. Use `send` when it's expected that the application will send a message to the given [`channel`](#user-content-operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#user-content-operationObjectChannel). +channel | [Reference Object](#user-content-referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. If the operation is located in the [root Operations Object](#user-content-operationsObject), it MUST point to a channel definition located in the [root Channels Object](#user-content-channelsObject), and MUST NOT point to a channel definition located in the [Components Object](#user-content-componentsObject) or anywhere else. If the operation is located in the [Components Object](#user-content-componentsObject), it MAY point to a [Channel Object](#channel-object) in any location. Please note the `channel` property value MUST be a [Reference Object](#user-content-referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channel-object). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +title | `string` | A human-friendly title for the operation. +summary | `string` | A short summary of what the operation is about. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. +security | [[Security Scheme Object](#user-content-securitySchemeObject) \| [Reference Object](#user-content-referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#user-content-securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#user-content-serverObjectSecurity) also applies, it MUST also be satisfied. +tags | [Tags Object](#tags-object) | A list of tags for logical grouping and categorization of operations. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this operation. +bindings | [Operation Bindings Object](#user-content-operationBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. +traits | [[Operation Trait Object](#user-content-operationTraitObject) &#user-content-124; [Reference Object](#user-content-referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged using [traits merge mechanism](#user-content-traits-merge-mechanism). The resulting object MUST be a valid [Operation Object](#operation-object). +messages | [[Reference Object](#user-content-referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#message-object) that can be processed by this operation. It MUST contain a subset of the messages defined in the [channel referenced in this operation](#user-content-operationObjectChannel), and MUST NOT point to a subset of message definitions located in the [Messages Object](#user-content-componentsMessages) in the [Components Object](#user-content-componentsObject) or anywhere else. **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#message-object) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#user-content-referenceObject) and, therefore, MUST NOT contain [Message Objects](#message-object). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +reply | [Operation Reply Object](#user-content-operationReplyObject) &#user-content-124; [Reference Object](#reference-object) | The definition of the reply in a request-reply operation. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Operation Object Example + +```json +{ + "title": "User sign up", + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "security": [ + { + "petstore_auth": [ + "write:pets", + "read:pets" + ] + } + ], + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { "$ref": "#/components/operationTraits/kafka" } + ], + "messages": [ + { "$ref": "/components/messages/userSignedUp" } + ], + "reply": { + "address": { + "location": "$message.header#/replyTo" + }, + "channel": { + "$ref": "#/channels/userSignupReply" + }, + "messages": [ + { "$ref": "/components/messages/userSignedUpReply" } + ], + } +} +``` + +```yaml +title: User sign up +summary: Action to sign a user up. +description: A longer description +channel: + $ref: '#/channels/userSignup' +action: send +security: + - petstore_auth: + - write:pets + - read:pets +tags: + - name: user + - name: signup + - name: register +bindings: + amqp: + ack: false +traits: + - $ref: "#/components/operationTraits/kafka" +messages: + - $ref: '#/components/messages/userSignedUp' +reply: + address: + location: '$message.header#/replyTo' + channel: + $ref: '#/channels/userSignupReply' + messages: + - $ref: '#/components/messages/userSignedUpReply' +``` + + + + +#### Operation Trait Object + +Describes a trait that MAY be applied to an [Operation Object](#operation-object). This object MAY contain any property from the [Operation Object](#operation-object), except the `action`, `channel`, `messages` and `traits` ones. + +If you're looking to apply traits to a message, see the [Message Trait Object](#message-trait-object). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +title | `string` | A human-friendly title for the operation. +summary | `string` | A short summary of what the operation is about. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +security | [[Security Scheme Object](#user-content-securitySchemeObject) \| [Reference Object](#user-content-referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#user-content-securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#user-content-serverObjectSecurity) also applies, it MUST also be satisfied. +tags | [Tags Object](#tags-object) | A list of tags for logical grouping and categorization of operations. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this operation. +bindings | [Operation Bindings Object](#user-content-operationBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Operation Trait Object Example + +```json +{ + "bindings": { + "amqp": { + "ack": false + } + } +} +``` + +```yaml +bindings: + amqp: + ack: false +``` + + + + +#### Operation Reply Object + +Describes the reply part that MAY be applied to an Operation Object. If an operation implements the request/reply pattern, the reply object represents the response message. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +address | [Operation Reply Address Object](#user-content-operationReplyAddressObject) &#user-content-124; [Reference Object](#reference-object) | Definition of the address that implementations MUST use for the reply. +channel | [Reference Object](#user-content-referenceObject) | A `$ref` pointer to the definition of the channel in which this operation is performed. When [address](#user-content-operationReplyAddressObject) is specified, the [`address` property](#channel-objectAddress) of the channel referenced by this property MUST be either `null` or not defined. If the operation reply is located inside a [root Operation Object](#user-content-operationObject), it MUST point to a channel definition located in the [root Channels Object](#user-content-channelsObject), and MUST NOT point to a channel definition located in the [Components Object](#user-content-componentsObject) or anywhere else. If the operation reply is located inside an [Operation Object] in the [Components Object](#user-content-componentsObject) or in the [Replies Object](#user-content-componentsReplies) in the [Components Object](#user-content-componentsObject), it MAY point to a [Channel Object](#channel-object) in any location. Please note the `channel` property value MUST be a [Reference Object](#user-content-referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channel-object). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +messages | [[Reference Object](#user-content-referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#message-object) that can be processed by this operation as reply. It MUST contain a subset of the messages defined in the [channel referenced in this operation reply](#user-content-operationObjectChannel), and MUST NOT point to a subset of message definitions located in the [Components Object](#user-content-componentsObject) or anywhere else. **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#message-object) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#user-content-referenceObject) and, therefore, MUST NOT contain [Message Objects](#message-object). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +#### Operation Reply Address Object + +An object that specifies where an operation has to send the reply. + +For specifying and computing the location of a reply address, a [runtime expression](#runtime-expression) is used. + + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- +description | `string` | An optional description of the address. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +location | `string` | **REQUIRED.** A [runtime expression](#runtime-expression) that specifies the location of the reply address. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Examples + +```json +{ + "description": "Consumer inbox", + "location": "$message.header#/replyTo" +} +``` + +```yaml +description: Consumer Inbox +location: $message.header#/replyTo +``` + + +#### Parameters Object + +Describes a map of parameters included in a channel address. + +This map MUST contain all the parameters used in the parent channel address. + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +`^[A-Za-z0-9_\-]+$` | [Parameter Object](#user-content-parameterObject) &#user-content-124; [Reference Object](#reference-object) | The key represents the name of the parameter. It MUST match the parameter name used in the parent channel address. + +##### Parameters Object Example + +```json +{ + "address": "user/{userId}/signedup", + "parameters": { + "userId": { + "description": "Id of the user." + } + } +} +``` + +```yaml +address: user/{userId}/signedup +parameters: + userId: + description: Id of the user. +``` + + + + + +#### Parameter Object + +Describes a parameter included in a channel address. + +##### 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 parameter. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +examples | [`string`] | An array of examples of the parameter value. +location | `string` | A [runtime expression](#runtime-expression) that specifies the location of the parameter value. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Parameter Object Example + +```json +{ + "address": "user/{userId}/signedup", + "parameters": { + "userId": { + "description": "Id of the user.", + "location": "$message.payload#/user/id" + } + } +} +``` + +```yaml +address: user/{userId}/signedup +parameters: + userId: + description: Id of the user. + location: $message.payload#/user/id +``` + + + + +#### Server Bindings Object + +Map describing protocol-specific definitions for a server. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Server Binding](https://github.com/asyncapi/bindings/blob/master/http#user-content-server) | Protocol-specific information for an HTTP server. +`ws` | [WebSockets Server Binding](https://github.com/asyncapi/bindings/blob/master/websockets#user-content-server) | Protocol-specific information for a WebSockets server. +`kafka` | [Kafka Server Binding](https://github.com/asyncapi/bindings/blob/master/kafka#user-content-server) | Protocol-specific information for a Kafka server. +`anypointmq` | [Anypoint MQ Server Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq#user-content-server) | Protocol-specific information for an Anypoint MQ server. +`amqp` | [AMQP Server Binding](https://github.com/asyncapi/bindings/blob/master/amqp#user-content-server) | Protocol-specific information for an AMQP 0-9-1 server. +`amqp1` | [AMQP 1.0 Server Binding](https://github.com/asyncapi/bindings/blob/master/amqp1#user-content-server) | Protocol-specific information for an AMQP 1.0 server. +`mqtt` | [MQTT Server Binding](https://github.com/asyncapi/bindings/blob/master/mqtt#user-content-server) | Protocol-specific information for an MQTT server. +`mqtt5` | [MQTT 5 Server Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5#user-content-server) | Protocol-specific information for an MQTT 5 server. +`nats` | [NATS Server Binding](https://github.com/asyncapi/bindings/blob/master/nats#user-content-server) | Protocol-specific information for a NATS server. +`jms` | [JMS Server Binding](https://github.com/asyncapi/bindings/blob/master/jms#user-content-server) | Protocol-specific information for a JMS server. +`sns` | [SNS Server Binding](https://github.com/asyncapi/bindings/blob/master/sns#user-content-server) | Protocol-specific information for an SNS server. +`solace` | [Solace Server Binding](https://github.com/asyncapi/bindings/blob/master/solace#user-content-server) | Protocol-specific information for a Solace server. +`sqs` | [SQS Server Binding](https://github.com/asyncapi/bindings/blob/master/sqs#user-content-server) | Protocol-specific information for an SQS server. +`stomp` | [STOMP Server Binding](https://github.com/asyncapi/bindings/blob/master/stomp#user-content-server) | Protocol-specific information for a STOMP server. +`redis` | [Redis Server Binding](https://github.com/asyncapi/bindings/blob/master/redis#user-content-server) | Protocol-specific information for a Redis server. +`mercure` | [Mercure Server Binding](https://github.com/asyncapi/bindings/blob/master/mercure#user-content-server) | Protocol-specific information for a Mercure server. +`ibmmq` | [IBM MQ Server Binding](https://github.com/asyncapi/bindings/blob/master/ibmmq#user-content-server-binding-object) | Protocol-specific information for an IBM MQ server. +`googlepubsub` | [Google Cloud Pub/Sub Server Binding](https://github.com/asyncapi/bindings/blob/master/googlepubsub#user-content-server) | Protocol-specific information for a Google Cloud Pub/Sub server. +`pulsar` | [Pulsar Server Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#user-content-server-binding-object) | Protocol-specific information for a Pulsar server. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + + + +#### Channel Bindings Object + +Map describing protocol-specific definitions for a channel. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Channel Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#user-content-channel) | Protocol-specific information for an HTTP channel. +`ws` | [WebSockets Channel Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#user-content-channel) | Protocol-specific information for a WebSockets channel. +`kafka` | [Kafka Channel Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#user-content-channel) | Protocol-specific information for a Kafka channel. +`anypointmq` | [Anypoint MQ Channel Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#user-content-channel) | Protocol-specific information for an Anypoint MQ channel. +`amqp` | [AMQP Channel Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#user-content-channel) | Protocol-specific information for an AMQP 0-9-1 channel. +`amqp1` | [AMQP 1.0 Channel Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#user-content-channel) | Protocol-specific information for an AMQP 1.0 channel. +`mqtt` | [MQTT Channel Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#user-content-channel) | Protocol-specific information for an MQTT channel. +`mqtt5` | [MQTT 5 Channel Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5#user-content-channel) | Protocol-specific information for an MQTT 5 channel. +`nats` | [NATS Channel Binding](https://github.com/asyncapi/bindings/blob/master/nats/README.md#user-content-channel) | Protocol-specific information for a NATS channel. +`jms` | [JMS Channel Binding](https://github.com/asyncapi/bindings/blob/master/jms/README.md#user-content-channel) | Protocol-specific information for a JMS channel. +`sns` | [SNS Channel Binding](https://github.com/asyncapi/bindings/blob/master/sns/README.md#user-content-channel) | Protocol-specific information for an SNS channel. +`solace` | [Solace Channel Binding](https://github.com/asyncapi/bindings/blob/master/solace#user-content-channel) | Protocol-specific information for a Solace channel. +`sqs` | [SQS Channel Binding](https://github.com/asyncapi/bindings/blob/master/sqs/README.md#user-content-channel) | Protocol-specific information for an SQS channel. +`stomp` | [STOMP Channel Binding](https://github.com/asyncapi/bindings/blob/master/stomp/README.md#user-content-channel) | Protocol-specific information for a STOMP channel. +`redis` | [Redis Channel Binding](https://github.com/asyncapi/bindings/blob/master/redis#user-content-channel) | Protocol-specific information for a Redis channel. +`mercure` | [Mercure Channel Binding](https://github.com/asyncapi/bindings/blob/master/mercure#user-content-channel) | Protocol-specific information for a Mercure channel. +`ibmmq` | [IBM MQ Channel Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#user-content-channel-binding-object) | Protocol-specific information for an IBM MQ channel. +`googlepubsub` | [Google Cloud Pub/Sub Channel Binding](https://github.com/asyncapi/bindings/tree/master/googlepubsub#user-content-channel) | Protocol-specific information for a Google Cloud Pub/Sub channel. +`pulsar` | [Pulsar Channel Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#user-content-channel-binding-object) | Protocol-specific information for a Pulsar channel. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + + + +#### Operation Bindings Object + +Map describing protocol-specific definitions for an operation. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Operation Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#user-content-operation) | Protocol-specific information for an HTTP operation. +`ws` | [WebSockets Operation Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#user-content-operation) | Protocol-specific information for a WebSockets operation. +`kafka` | [Kafka Operation Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#user-content-operation) | Protocol-specific information for a Kafka operation. +`anypointmq` | [Anypoint MQ Operation Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#user-content-operation) | Protocol-specific information for an Anypoint MQ operation. +`amqp` | [AMQP Operation Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#user-content-operation) | Protocol-specific information for an AMQP 0-9-1 operation. +`amqp1` | [AMQP 1.0 Operation Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#user-content-operation) | Protocol-specific information for an AMQP 1.0 operation. +`mqtt` | [MQTT Operation Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#user-content-operation) | Protocol-specific information for an MQTT operation. +`mqtt5` | [MQTT 5 Operation Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5/README.md#user-content-operation) | Protocol-specific information for an MQTT 5 operation. +`nats` | [NATS Operation Binding](https://github.com/asyncapi/bindings/blob/master/nats/README.md#user-content-operation) | Protocol-specific information for a NATS operation. +`jms` | [JMS Operation Binding](https://github.com/asyncapi/bindings/blob/master/jms/README.md#user-content-operation) | Protocol-specific information for a JMS operation. +`sns` | [SNS Operation Binding](https://github.com/asyncapi/bindings/blob/master/sns/README.md#user-content-operation) | Protocol-specific information for an SNS operation. +`solace` | [Solace Operation Binding](https://github.com/asyncapi/bindings/blob/master/solace#user-content-operation) | Protocol-specific information for a Solace operation. +`sqs` | [SQS Operation Binding](https://github.com/asyncapi/bindings/blob/master/sqs/README.md#user-content-operation) | Protocol-specific information for an SQS operation. +`stomp` | [STOMP Operation Binding](https://github.com/asyncapi/bindings/blob/master/stomp/README.md#user-content-operation) | Protocol-specific information for a STOMP operation. +`redis` | [Redis Operation Binding](https://github.com/asyncapi/bindings/blob/master/redis#user-content-operation) | Protocol-specific information for a Redis operation. +`mercure` | [Mercure Operation Binding](https://github.com/asyncapi/bindings/blob/master/mercure#user-content-operation) | Protocol-specific information for a Mercure operation. +`googlepubsub` | [Google Cloud Pub/Sub Operation Binding](https://github.com/asyncapi/bindings/blob/master/googlepubsub#user-content-operation) | Protocol-specific information for a Google Cloud Pub/Sub operation. +`ibmmq` | [IBM MQ Operation Binding](https://github.com/asyncapi/bindings/blob/master/ibmmq#user-content-operation-binding-object) | Protocol-specific information for an IBM MQ operation. +`pulsar` | [Pulsar Operation Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#user-content-operation-binding-fields) | Protocol-specific information for a Pulsar operation. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + + + + +#### Message Bindings Object + +Map describing protocol-specific definitions for a message. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Message Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#user-content-message) | Protocol-specific information for an HTTP message, i.e., a request or a response. +`ws` | [WebSockets Message Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#user-content-message) | Protocol-specific information for a WebSockets message. +`kafka` | [Kafka Message Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#user-content-message) | Protocol-specific information for a Kafka message. +`anypointmq` | [Anypoint MQ Message Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#user-content-message) | Protocol-specific information for an Anypoint MQ message. +`amqp` | [AMQP Message Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#user-content-message) | Protocol-specific information for an AMQP 0-9-1 message. +`amqp1` | [AMQP 1.0 Message Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#user-content-message) | Protocol-specific information for an AMQP 1.0 message. +`mqtt` | [MQTT Message Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#user-content-message) | Protocol-specific information for an MQTT message. +`mqtt5` | [MQTT 5 Message Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5/README.md#user-content-message) | Protocol-specific information for an MQTT 5 message. +`nats` | [NATS Message Binding](https://github.com/asyncapi/bindings/blob/master/nats/README.md#user-content-message) | Protocol-specific information for a NATS message. +`jms` | [JMS Message Binding](https://github.com/asyncapi/bindings/blob/master/jms/README.md#user-content-message) | Protocol-specific information for a JMS message. +`sns` | [SNS Message Binding](https://github.com/asyncapi/bindings/blob/master/sns/README.md#user-content-message) | Protocol-specific information for an SNS message. +`solace` | [Solace Server Binding](https://github.com/asyncapi/bindings/blob/master/solace#user-content-message) | Protocol-specific information for a Solace message. +`sqs` | [SQS Message Binding](https://github.com/asyncapi/bindings/blob/master/sqs/README.md#user-content-message) | Protocol-specific information for an SQS message. +`stomp` | [STOMP Message Binding](https://github.com/asyncapi/bindings/blob/master/stomp/README.md#user-content-message) | Protocol-specific information for a STOMP message. +`redis` | [Redis Message Binding](https://github.com/asyncapi/bindings/blob/master/redis#user-content-message) | Protocol-specific information for a Redis message. +`mercure` | [Mercure Message Binding](https://github.com/asyncapi/bindings/blob/master/mercure#user-content-message) | Protocol-specific information for a Mercure message. +`ibmmq` | [IBM MQ Message Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#user-content-message-binding-object) | Protocol-specific information for an IBM MQ message. +`googlepubsub` | [Google Cloud Pub/Sub Message Binding](https://github.com/asyncapi/bindings/tree/master/googlepubsub#user-content-message) | Protocol-specific information for a Google Cloud Pub/Sub message. +`pulsar` | [Pulsar Message Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#user-content-message-binding-fields) | Protocol-specific information for a Pulsar message. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + + + + + + + +#### Message Object + +Describes a message received on a given channel and operation. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +headers | [Multi Format Schema Object](#user-content-multiFormatSchemaObject) &#user-content-124; [Schema Object](#user-content-schemaObject) &#user-content-124; [Reference Object](#user-content-referenceObject) | Schema definition of the application headers. Schema MUST be a map of key-value pairs. It **MUST NOT** define the protocol headers. If this is a [Schema Object](#user-content-schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#asyncapi-version-string). +payload | [Multi Format Schema Object](#user-content-multiFormatSchemaObject) &#user-content-124; [Schema Object](#user-content-schemaObject) &#user-content-124; [Reference Object](#user-content-referenceObject) | Definition of the message payload. If this is a [Schema Object](#user-content-schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#asyncapi-version-string). +correlationId | [Correlation ID Object](#user-content-correlationIdObject) &#user-content-124; [Reference Object](#reference-object) | Definition of the correlation ID used for message tracing or matching. +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](#default-content-type) 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](https://spec.commonmark.org/) can be used for rich text representation. +tags | [Tags Object](#tags-object) | A list of tags for logical grouping and categorization of messages. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this message. +bindings | [Message Bindings Object](#user-content-messageBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. +examples | [[Message Example Object](#message-example-object)] | List of examples. +traits | [[Message Trait Object](#user-content-messageTraitObject) &#user-content-124; [Reference Object](#user-content-referenceObject)] | A list of traits to apply to the message object. Traits MUST be merged using [traits merge mechanism](#user-content-traits-merge-mechanism). The resulting object MUST be a valid [Message Object](#message-object). + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Message Object Example + +```json +{ + "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": { + "type": "object", + "properties": { + "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" + }, + "traits": [ + { "$ref": "#/components/messageTraits/commonHeaders" } + ], + "examples": [ + { + "name": "SimpleSignup", + "summary": "A simple UserSignup example message", + "headers": { + "correlationId": "my-correlation-id", + "applicationInstanceId": "myInstanceId" + }, + "payload": { + "user": { + "someUserKey": "someUserValue" + }, + "signup": { + "someSignupKey": "someSignupValue" + } + } + } + ] +} +``` + +```yaml +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: + type: object + properties: + 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 +traits: + - $ref: "#/components/messageTraits/commonHeaders" +examples: + - name: SimpleSignup + summary: A simple UserSignup example message + headers: + correlationId: my-correlation-id + applicationInstanceId: myInstanceId + payload: + user: + someUserKey: someUserValue + signup: + someSignupKey: someSignupValue +``` + +Example using Avro to define the payload: + +```json +{ + "name": "UserSignup", + "title": "User signup", + "summary": "Action to sign a user up.", + "description": "A longer description", + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "payload": { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "schema": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } +} +``` + +```yaml +name: UserSignup +title: User signup +summary: Action to sign a user up. +description: A longer description +tags: + - name: user + - name: signup + - name: register +payload: + schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' + schema: + $ref: 'path/to/user-create.avsc/#user-content-UserCreate' +``` + + + + + + + +#### Message Trait Object + +Describes a trait that MAY be applied to a [Message Object](#message-object). This object MAY contain any property from the [Message Object](#message-object), except `payload` and `traits`. + +If you're looking to apply traits to an operation, see the [Operation Trait Object](#operation-trait-object). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +headers | [Multi Format Schema Object](#user-content-multiFormatSchemaObject) &#user-content-124; [Schema Object](#user-content-schemaObject) &#user-content-124; [Reference Object](#user-content-referenceObject) | Schema definition of the application headers. Schema MUST be a map of key-value pairs. It **MUST NOT** define the protocol headers. If this is a [Schema Object](#user-content-schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#asyncapi-version-string). +correlationId | [Correlation ID Object](#user-content-correlationIdObject) &#user-content-124; [Reference Object](#reference-object) | Definition of the correlation ID used for message tracing or matching. +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](#default-content-type) 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](https://spec.commonmark.org/) can be used for rich text representation. +tags | [Tags Object](#tags-object) | A list of tags for logical grouping and categorization of messages. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this message. +bindings | [Message Bindings Object](#user-content-messageBindingsObject) \| [Reference Object](#reference-object) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. +examples | [[Message Example Object](#message-example-object)] | List of examples. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Message Trait Object Example + +```json +{ + "contentType": "application/json" +} +``` + +```yaml +contentType: application/json +``` + +#### Message Example Object + +Message Example Object represents an example of a [Message Object](#message-object) and MUST contain either **headers** and/or **payload** fields. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +headers | `Map[string, any]` | The value of this field MUST validate against the [Message Object's headers](#user-content-messageObjectHeaders) field. +payload | `Map[string, any]` | The value of this field MUST validate against the [Message Object's payload](#user-content-messageObjectPayload) field. +name | `string` | A machine-friendly name. +summary | `string` | A short summary of what the example is about. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Message Example Object Example + +```json +{ + "name": "SimpleSignup", + "summary": "A simple UserSignup example message", + "headers": { + "correlationId": "my-correlation-id", + "applicationInstanceId": "myInstanceId" + }, + "payload": { + "user": { + "someUserKey": "someUserValue" + }, + "signup": { + "someSignupKey": "someSignupValue" + } + } +} +``` + +```yaml +name: SimpleSignup +summary: A simple UserSignup example message +headers: + correlationId: my-correlation-id + applicationInstanceId: myInstanceId +payload: + user: + someUserKey: someUserValue + signup: + someSignupKey: someSignupValue +``` + +#### Tags Object + +A Tags object is a list of [Tag Objects](#user-content-tagObject). An [Tag Object](#user-content-tagObject) in a list can be referenced by [Reference Object](#reference-object). + +#### 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](https://spec.commonmark.org/) can be used for rich text representation. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this tag. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Tag Object Example + +```json +{ + "name": "user", + "description": "User-related messages" +} +``` + +```yaml +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](https://spec.commonmark.org/) can be used for rich text representation. +url | `string` | **REQUIRED.** The URL for the target documentation. This MUST be in the form of an absolute URL. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### External Documentation Object Example + +```json +{ + "description": "Find more info here", + "url": "https://example.com" +} +``` + +```yaml +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](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules. A JSON Reference SHALL only be used to refer to a schema that is formatted in either JSON or YAML. In the case of a YAML-formatted Schema, the JSON Reference SHALL be applied to the JSON representation of that schema. The JSON representation SHALL be made by applying the conversion described [here](#format). + +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 + +```json +{ + "$ref": "#/components/schemas/Pet" +} +``` + +```yaml + $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`, [Multi Format Schema Object](#user-content-multiFormatSchemaObject) \| [Schema Object](#user-content-schemaObject) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Schema Object](#user-content-schemaObject). If this is a [Schema Object](#user-content-schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#asyncapi-version-string). + servers | Map[`string`, [Server Object](#server-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Server Objects](#server-object). + channels | Map[`string`, [Channel Object](#channel-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Channel Objects](#channel-object). + operations | Map[`string`, [Operation Object](#operation-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Operation Objects](#operation-object). + messages | Map[`string`, [Message Object](#message-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Message Objects](#message-object). + securitySchemes| Map[`string`, [Security Scheme Object](#security-scheme-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Security Scheme Objects](#security-scheme-object). + serverVariables | Map[`string`, [Server Variable Object](#server-variable-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Server Variable Objects](#server-variable-object). + parameters | Map[`string`, [Parameter Object](#parameter-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Parameter Objects](#parameter-object). + correlationIds | Map[`string`, [Correlation ID Object](#correlation-id-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Correlation ID Objects](#correlation-id-object). +replies | Map[`string`, [Operation Reply Object](#operation-reply-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Operation Reply Objects](#operation-reply-object). + replyAddresses | Map[`string`, [Operation Reply Address Object](#operation-reply-address-object) &#user-content-124; [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Operation Reply Address Objects](#operation-reply-address-object). + externalDocs | Map[`string`, [External Documentation Object](#external-documentation-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [External Documentation Objects](#external-documentation-object). + tags | Map[`string`, [Tag Object](#tag-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Tag Objects](#tag-object). + operationTraits | Map[`string`, [Operation Trait Object](#operation-trait-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Operation Trait Objects](#operation-trait-object). + messageTraits | Map[`string`, [Message Trait Object](#message-trait-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Message Trait Objects](#message-trait-object). + serverBindings | Map[`string`, [Server Bindings Object](#server-bindings-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Server Bindings Objects](#server-bindings-object). + channelBindings | Map[`string`, [Channel Bindings Object](#channel-bindings-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Channel Bindings Objects](#channel-bindings-object). + operationBindings | Map[`string`, [Operation Bindings Object](#operation-bindings-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Operation Bindings Objects](#operation-bindings-object). + messageBindings | Map[`string`, [Message Bindings Object](#message-bindings-object) \| [Reference Object](#user-content-referenceObject)] | An object to hold reusable [Message Bindings Objects](#message-bindings-object). + +This object MAY be extended with [Specification Extensions](#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 + +```json +{ + "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" + } + } + }, + "AvroExample": { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "schema": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } + }, + "servers": { + "development": { + "host": "{stage}.in.mycompany.com:{port}", + "description": "RabbitMQ broker", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "variables": { + "stage": { + "$ref": "#/components/serverVariables/stage" + }, + "port": { + "$ref": "#/components/serverVariables/port" + } + } + } + }, + "serverVariables": { + "stage": { + "default": "demo", + "description": "This value is assigned by the service provider, in this example `mycompany.com`" + }, + "port": { + "enum": ["5671", "5672"], + "default": "5672" + } + }, + "channels": { + "user/signedup": { + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignUp" + } + } + } + }, + "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": { + "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": { + "description": "Id of the user." + } + }, + "correlationIds": { + "default": { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + } + }, + "messageTraits": { + "commonHeaders": { + "headers": { + "type": "object", + "properties": { + "my-app-header": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + } + } + } + } + } +} +``` + +```yaml +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 + AvroExample: + schemaFormat: application/vnd.apache.avro+json;version=1.9.0 + schema: + $ref: 'path/to/user-create.avsc/#user-content-UserCreate' + servers: + development: + host: "{stage}.in.mycompany.com:{port}" + description: RabbitMQ broker + protocol: amqp + protocolVersion: 0-9-1 + variables: + stage: + $ref: "#/components/serverVariables/stage" + port: + $ref: "#/components/serverVariables/port" + serverVariables: + stage: + default: demo + description: This value is assigned by the service provider, in this example `mycompany.com` + port: + enum: ["5671", "5672"] + default: "5672" + channels: + user/signedup: + subscribe: + message: + $ref: "#/components/messages/userSignUp" + 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: + 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: + description: Id of the user. + correlationIds: + default: + description: Default Correlation ID + location: $message.header#/correlationId + messageTraits: + commonHeaders: + headers: + type: object + properties: + my-app-header: + type: integer + minimum: 0 + maximum: 100 +``` + +#### Multi Format Schema Object + +The Multi Format Schema Object represents a schema definition. It differs from the [Schema Object](#schema-object) in that it supports multiple schema formats or languages (e.g., JSON Schema, Avro, etc.). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +schemaFormat | `string` | **Required**. A string containing the name of the schema format that is used to define the information. If `schemaFormat` is missing, it MUST default to `application/vnd.aai.asyncapi+json;version={{asyncapi}}` where `{{asyncapi}}` matches the [AsyncAPI Version String](#user-content-A2SVersionString). In such a case, this would make the Multi Format Schema Object equivalent to the [Schema Object](#user-content-schemaObject). When using [Reference Object](#reference-object) within the schema, the `schemaFormat` of the resource being referenced MUST match the `schemaFormat` of the schema that contains the initial reference. For example, if you reference Avro `schema`, then `schemaFormat` of referencing resource and the resource being reference MUST match.
Check out the [supported schema formats table](#user-content-multiFormatSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#user-content-multiFormatSchemaFormatTable).
When using [Reference Objects](#reference-object) within the schema, the `schemaFormat` of the referenced resource MUST match the `schemaFormat` of the schema containing the reference. +schema | `any` | **Required**. Definition of the message payload. It can be of any type but defaults to [Schema Object](#user-content-schemaObject). It MUST match the schema format defined in [`schemaFormat`](#user-content-multiFormatSchemaObjectSchemaFormat), including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Schema formats table + +The following table contains a set of values that every implementation MUST support. + +Name | Allowed values | Notes +---|:---:|--- +[AsyncAPI 3.0.0 Schema Object](#schema-object) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided. +[JSON Schema Draft 07](https://json-schema.org/specification-links.html#user-content-draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | + +The following table contains a set of values that every implementation is RECOMMENDED to support. + +Name | Allowed values | Notes +---|:---:|--- +[Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#user-content-schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` | +[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#user-content-schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | +[RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` | +[Protocol Buffers](https://protobuf.dev/) | `application/vnd.google.protobuf;version=2`, `application/vnd.google.protobuf;version=3` | + + +#### Schema Object + +The Schema Object allows the definition of input and output data types. +These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/). The empty schema (which allows any instance to validate) MAY be represented by the `boolean` value `true` and a schema which allows no instance to validate MAY be represented by the `boolean` value `false`. + +Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-handrews-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01). +Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. For other formats (e.g., Avro, RAML, etc) see [Multi Format Schema Object](#multiFormatSchemaObject). + +##### Properties + +The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such, any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to: + +- title +- type +- required +- multipleOf +- maximum +- exclusiveMaximum +- minimum +- exclusiveMinimum +- maxLength +- minLength +- pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#user-content-sec-7.8.5) dialect) +- maxItems +- minItems +- uniqueItems +- maxProperties +- minProperties +- enum +- const +- examples +- if / then / else +- readOnly +- writeOnly +- properties +- patternProperties +- additionalProperties +- additionalItems +- items +- propertyNames +- contains +- allOf +- oneOf +- anyOf +- not + +The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. + +- description - [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +- format - See [Data Type Formats](#data-type-formats) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. +- default - Use it to specify that property has a predefined value if no other value is present. 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](#reference-object) can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the `$ref` keyword MUST follow the behavior described by [Reference Object](#reference-object) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#user-content-ref). + +In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#composition-and-inheritance-(polymorphism)) for more details. +externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this schema. + deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. + +This object MAY be extended with [Specification Extensions](#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 two ways to define the value of a discriminator for an inheriting instance. + +- Use the schema's name. +- Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. + +As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. + +##### Schema Object Examples + +###### Primitive Sample + +```json +{ + "type": "string", + "format": "email" +} +``` + +```yaml +type: string +format: email +``` + +###### Simple Model + +```json +{ + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "address": { + "$ref": "#/components/schemas/Address" + }, + "age": { + "type": "integer", + "format": "int32", + "minimum": 0 + } + } +} +``` + +```yaml +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: + +```json +{ + "type": "object", + "additionalProperties": { + "type": "string" + } +} +``` + +```yaml +type: object +additionalProperties: + type: string +``` + +For a string to model mapping: + +```json +{ + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/ComplexModel" + } +} +``` + +```yaml +type: object +additionalProperties: + $ref: '#/components/schemas/ComplexModel' +``` + +###### Model with Example + +```json +{ + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "examples": [ + { + "name": "Puma", + "id": 1 + } + ] +} +``` + +```yaml +type: object +properties: + id: + type: integer + format: int64 + name: + type: string +required: +- name +examples: +- name: Puma + id: 1 +``` + +###### Model with Boolean Schemas + +```json +{ + "type": "object", + "required": [ + "anySchema" + ], + "properties": { + "anySchema": true, + "cannotBeDefined": false + } +} +``` + +```yaml +type: object +required: +- anySchema +properties: + anySchema: true + cannotBeDefined: false +``` + +###### Models with Composition + +```json +{ + "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" + } + } + } + ] + } + } +} +``` + +```yaml +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 + +```json +{ + "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" + ] + } + ] + }, + "StickInsect": { + "description": "A representation of an Australian walking stick. Note that `StickBug` will be used as the discriminator value.", + "allOf": [ + { + "$ref": "#/components/schemas/Pet" + }, + { + "type": "object", + "properties": { + "petType": { + "const": "StickBug" + }, + "color": { + "type": "string" + } + }, + "required": [ + "color" + ] + } + ] + } + } +} +``` + +```yaml +schemas: + Pet: + type: object + discriminator: petType + properties: + name: + type: string + petType: + type: string + required: + - name + - petType + ## applies to instances with `petType: "Cat"` + ## because that is the schema name + Cat: + 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 + ## applies to instances with `petType: "Dog"` + ## because that is the schema name + Dog: + 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 + ## applies to instances with `petType: "StickBug"` + ## because that is the required value of the discriminator field, + ## overriding the schema name + StickInsect: + description: A representation of an Australian walking stick + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + properties: + petType: + const: StickBug + color: + type: string + required: + - color +``` + + + + + +#### Security Scheme Object + +Defines a security scheme that can be used by the operations. Supported schemes are: + +* User/Password. +* API key (either as user or as password). +* X.509 certificate. +* End-to-end encryption (either symmetric or asymmetric). +* HTTP authentication. +* HTTP API key. +* OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749). +* [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). +* SASL (Simple Authentication and Security Layer) as defined in [RFC4422](https://tools.ietf.org/html/rfc4422). + +##### 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"`, `"oauth2"`, `"openIdConnect"`, `"plain"`, `"scramSha256"`, `"scramSha512"`, and `"gssapi"`. +description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) 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](https://tools.ietf.org/html/rfc7235#user-content-section-5.1). +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](#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 an absolute URL. +scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Security Scheme Object Example + +###### User/Password Authentication Sample + +```json +{ + "type": "userPassword" +} +``` + +```yaml +type: userPassword +``` + +###### API Key Authentication Sample + +```json +{ + "type": "apiKey", + "in": "user" +} +``` + +```yaml +type: apiKey +in: user +``` + +###### X.509 Authentication Sample + +```json +{ + "type": "X509" +} +``` + +```yaml +type: X509 +``` + +###### End-to-end Encryption Authentication Sample + +```json +{ + "type": "symmetricEncryption" +} +``` + +```yaml +type: symmetricEncryption +``` + +###### Basic Authentication Sample + +```json +{ + "type": "http", + "scheme": "basic" +} +``` + +```yaml +type: http +scheme: basic +``` + +###### API Key Sample + +```json +{ + "type": "httpApiKey", + "name": "api_key", + "in": "header" +} +``` + +```yaml +type: httpApiKey +name: api_key +in: header +``` + +###### JWT Bearer Sample + +```json +{ + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT" +} +``` + +```yaml +type: http +scheme: bearer +bearerFormat: JWT +``` + +###### Implicit OAuth2 Sample + +```json +{ + "type": "oauth2", + "flows": { + "implicit": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } + }, + "scopes": [ + "write:pets" + ] +} +``` + +```yaml +type: oauth2 +flows: + implicit: + authorizationUrl: https://example.com/api/oauth/dialog + availableScopes: + write:pets: modify pets in your account + read:pets: read your pets +scopes: + - 'write:pets' +``` + +###### SASL Sample + +```json +{ + "type": "scramSha512" +} +``` + +```yaml +type: scramSha512 +``` + +#### OAuth Flows Object + +Allows configuration of the supported OAuth Flows. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +implicit| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Implicit flow. +password| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Resource Owner Protected Credentials flow. +clientCredentials| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. +authorizationCode| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. + +This object MAY be extended with [Specification Extensions](#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 an absolute URL. +tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. +refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. +availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### OAuth Flow Object Examples + +```JSON +{ + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } +} +``` + +```YAML +authorizationUrl: https://example.com/api/oauth/dialog +tokenUrl: https://example.com/api/oauth/token +availableScopes: + write:pets: modify pets in your account + read:pets: read your pets +``` + + + +### 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](#runtime-expression) is used. + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- +description | `string` | An optional description of the identifier. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +location | `string` | **REQUIRED.** A [runtime expression](#runtime-expression) that specifies the location of the correlation ID. + +This object MAY be extended with [Specification Extensions](#specification-extensions). + +##### Examples + +```json +{ + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" +} +``` + +```yaml +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](#user-content-correlationIdObject) and [Operation Reply Address Object](#operation-reply-address-object). + +The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) 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. + +### Traits Merge Mechanism + +Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the target object. + +#### Example + +An object like the following: + +```yaml +description: A longer description. +traits: + - name: UserSignup + description: Description from trait. + - tags: + - name: user +``` + +Would look like the following after applying traits: + +```yaml +name: UserSignup +description: A longer description. +tags: + - name: user +``` + +### 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`](#data-type-formats) | 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](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) +dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) +password | `string` | `password` | Used to hint UIs the input needs to be obscured. From 73a612e9b2162c1f7cc2655a762d162432e8cb36 Mon Sep 17 00:00:00 2001 From: Pavel Bodiachevskii
Check out the [supported schema formats table](#user-content-multiFormatSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#user-content-multiFormatSchemaFormatTable).
When using [Reference Objects](#reference-object) within the schema, the `schemaFormat` of the referenced resource MUST match the `schemaFormat` of the schema containing the reference. -schema | `any` | **Required**. Definition of the message payload. It can be of any type but defaults to [Schema Object](#user-content-schemaObject). It MUST match the schema format defined in [`schemaFormat`](#user-content-multiFormatSchemaObjectSchemaFormat), including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Schema formats table - -The following table contains a set of values that every implementation MUST support. - -Name | Allowed values | Notes ----|:---:|--- -[AsyncAPI 3.0.0 Schema Object](#schema-object) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided. -[JSON Schema Draft 07](https://json-schema.org/specification-links.html#user-content-draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | - -The following table contains a set of values that every implementation is RECOMMENDED to support. - -Name | Allowed values | Notes ----|:---:|--- -[Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#user-content-schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` | -[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#user-content-schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | -[RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` | -[Protocol Buffers](https://protobuf.dev/) | `application/vnd.google.protobuf;version=2`, `application/vnd.google.protobuf;version=3` | - - -#### Schema Object - -The Schema Object allows the definition of input and output data types. -These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/). The empty schema (which allows any instance to validate) MAY be represented by the `boolean` value `true` and a schema which allows no instance to validate MAY be represented by the `boolean` value `false`. - -Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-handrews-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01). -Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. For other formats (e.g., Avro, RAML, etc) see [Multi Format Schema Object](#multiFormatSchemaObject). - -##### Properties - -The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such, any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to: - -- title -- type -- required -- multipleOf -- maximum -- exclusiveMaximum -- minimum -- exclusiveMinimum -- maxLength -- minLength -- pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#user-content-sec-7.8.5) dialect) -- maxItems -- minItems -- uniqueItems -- maxProperties -- minProperties -- enum -- const -- examples -- if / then / else -- readOnly -- writeOnly -- properties -- patternProperties -- additionalProperties -- additionalItems -- items -- propertyNames -- contains -- allOf -- oneOf -- anyOf -- not - -The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. - -- description - [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -- format - See [Data Type Formats](#data-type-formats) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. -- default - Use it to specify that property has a predefined value if no other value is present. 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](#reference-object) can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the `$ref` keyword MUST follow the behavior described by [Reference Object](#reference-object) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#user-content-ref). - -In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#composition-and-inheritance-(polymorphism)) for more details. -externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this schema. - deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. - -This object MAY be extended with [Specification Extensions](#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 two ways to define the value of a discriminator for an inheriting instance. - -- Use the schema's name. -- Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. - -As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. - -##### Schema Object Examples - -###### Primitive Sample - -```json -{ - "type": "string", - "format": "email" -} -``` - -```yaml -type: string -format: email -``` - -###### Simple Model - -```json -{ - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "age": { - "type": "integer", - "format": "int32", - "minimum": 0 - } - } -} -``` - -```yaml -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: - -```json -{ - "type": "object", - "additionalProperties": { - "type": "string" - } -} -``` - -```yaml -type: object -additionalProperties: - type: string -``` - -For a string to model mapping: - -```json -{ - "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/ComplexModel" - } -} -``` - -```yaml -type: object -additionalProperties: - $ref: '#/components/schemas/ComplexModel' -``` - -###### Model with Example - -```json -{ - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - }, - "required": [ - "name" - ], - "examples": [ - { - "name": "Puma", - "id": 1 - } - ] -} -``` - -```yaml -type: object -properties: - id: - type: integer - format: int64 - name: - type: string -required: -- name -examples: -- name: Puma - id: 1 -``` - -###### Model with Boolean Schemas - -```json -{ - "type": "object", - "required": [ - "anySchema" - ], - "properties": { - "anySchema": true, - "cannotBeDefined": false - } -} -``` - -```yaml -type: object -required: -- anySchema -properties: - anySchema: true - cannotBeDefined: false -``` - -###### Models with Composition - -```json -{ - "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" - } - } - } - ] - } - } -} -``` - -```yaml -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 - -```json -{ - "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" - ] - } - ] - }, - "StickInsect": { - "description": "A representation of an Australian walking stick. Note that `StickBug` will be used as the discriminator value.", - "allOf": [ - { - "$ref": "#/components/schemas/Pet" - }, - { - "type": "object", - "properties": { - "petType": { - "const": "StickBug" - }, - "color": { - "type": "string" - } - }, - "required": [ - "color" - ] - } - ] - } - } -} -``` - -```yaml -schemas: - Pet: - type: object - discriminator: petType - properties: - name: - type: string - petType: - type: string - required: - - name - - petType - ## applies to instances with `petType: "Cat"` - ## because that is the schema name - Cat: - 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 - ## applies to instances with `petType: "Dog"` - ## because that is the schema name - Dog: - 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 - ## applies to instances with `petType: "StickBug"` - ## because that is the required value of the discriminator field, - ## overriding the schema name - StickInsect: - description: A representation of an Australian walking stick - allOf: - - $ref: '#/components/schemas/Pet' - - type: object - properties: - petType: - const: StickBug - color: - type: string - required: - - color -``` - - - - - -#### Security Scheme Object - -Defines a security scheme that can be used by the operations. Supported schemes are: - -* User/Password. -* API key (either as user or as password). -* X.509 certificate. -* End-to-end encryption (either symmetric or asymmetric). -* HTTP authentication. -* HTTP API key. -* OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749). -* [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). -* SASL (Simple Authentication and Security Layer) as defined in [RFC4422](https://tools.ietf.org/html/rfc4422). - -##### 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"`, `"oauth2"`, `"openIdConnect"`, `"plain"`, `"scramSha256"`, `"scramSha512"`, and `"gssapi"`. -description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) 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](https://tools.ietf.org/html/rfc7235#user-content-section-5.1). -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](#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 an absolute URL. -scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Security Scheme Object Example - -###### User/Password Authentication Sample - -```json -{ - "type": "userPassword" -} -``` - -```yaml -type: userPassword -``` - -###### API Key Authentication Sample - -```json -{ - "type": "apiKey", - "in": "user" -} -``` - -```yaml -type: apiKey -in: user -``` - -###### X.509 Authentication Sample - -```json -{ - "type": "X509" -} -``` - -```yaml -type: X509 -``` - -###### End-to-end Encryption Authentication Sample - -```json -{ - "type": "symmetricEncryption" -} -``` - -```yaml -type: symmetricEncryption -``` - -###### Basic Authentication Sample - -```json -{ - "type": "http", - "scheme": "basic" -} -``` - -```yaml -type: http -scheme: basic -``` - -###### API Key Sample - -```json -{ - "type": "httpApiKey", - "name": "api_key", - "in": "header" -} -``` - -```yaml -type: httpApiKey -name: api_key -in: header -``` - -###### JWT Bearer Sample - -```json -{ - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT" -} -``` - -```yaml -type: http -scheme: bearer -bearerFormat: JWT -``` - -###### Implicit OAuth2 Sample - -```json -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "availableScopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - }, - "scopes": [ - "write:pets" - ] -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - availableScopes: - write:pets: modify pets in your account - read:pets: read your pets -scopes: - - 'write:pets' -``` - -###### SASL Sample - -```json -{ - "type": "scramSha512" -} -``` - -```yaml -type: scramSha512 -``` - -#### OAuth Flows Object - -Allows configuration of the supported OAuth Flows. - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -implicit| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Implicit flow. -password| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Resource Owner Protected Credentials flow. -clientCredentials| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. -authorizationCode| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. - -This object MAY be extended with [Specification Extensions](#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 an absolute URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. -availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### OAuth Flow Object Examples - -```JSON -{ - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "availableScopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } -} -``` - -```YAML -authorizationUrl: https://example.com/api/oauth/dialog -tokenUrl: https://example.com/api/oauth/token -availableScopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - - - -### 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](#runtime-expression) is used. - -##### Fixed Fields - -Field Name | Type | Description ----|:---|--- -description | `string` | An optional description of the identifier. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -location | `string` | **REQUIRED.** A [runtime expression](#runtime-expression) that specifies the location of the correlation ID. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Examples - -```json -{ - "description": "Default Correlation ID", - "location": "$message.header#/correlationId" -} -``` - -```yaml -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](#user-content-correlationIdObject) and [Operation Reply Address Object](#operation-reply-address-object). - -The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) 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. - -### Traits Merge Mechanism - -Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the target object. - -#### Example - -An object like the following: - -```yaml -description: A longer description. -traits: - - name: UserSignup - description: Description from trait. - - tags: - - name: user -``` - -Would look like the following after applying traits: - -```yaml -name: UserSignup -description: A longer description. -tags: - - name: user -``` - -### 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`](#data-type-formats) | 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](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) -dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) -password | `string` | `password` | Used to hint UIs the input needs to be obscured. +# AsyncAPI Specification + +#### Attribution + +Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). + +#### Version 3.0.0 + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). + +The AsyncAPI Specification is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). + +## Introduction + +The AsyncAPI Specification is a project used to describe message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). + +The AsyncAPI Specification defines a set of fields that can be used in an AsyncAPI document to describe an [application](#definitionsApplication)'s API. The document may reference other files for additional details or shared fields, but it is typically a single, primary document that encapsulates the API description. + +The AsyncAPI document SHOULD describe the operations an [application](#definitionsApplication) performs. For instance, consider the following AsyncAPI definition snippet: + +```yaml +channels: + userSignedUp: + # ...(redacted for brevity) +operations: + onUserSignedUp: + action: receive + channel: + $ref: "#/channels/userSignedUp" +``` + +It means that the [application](#definitionsApplication) will receive messages from the `userSignedUp` [channel](#definitionsChannel). + +**The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol. + +It's NOT RECOMMENDED to derive a [receiver](#definitionsReceiver) AsyncAPI document from a [sender](#definitionsSender) one or vice versa. There are no guarantees that the channel used by an application to receive messages will be the same channel where another application is sending them. Also, certain fields in the document like `summary`, `description`, and the id of the operation might stop making sense. For instance, given the following receiver snippet: + +```yaml +operations: + onUserSignedUp: + summary: On user signed up. + description: Event received when a user signed up on the product. + action: receive + channel: + $ref: "#/channels/userSignedUp" +``` + +We can't automatically assume that an _opposite_ application exists by simply replacing `receive` with `send`: + +```yaml +operations: + onUserSignedUp: # <-- This doesn't make sense now. Should be something like sendUserSignedUp. + summary: On user signed up. # <-- This doesn't make sense now. Should say something like "Sends a user signed up event". + description: Event received when a user signed up on the product. # <-- This doesn't make sense now. Should speak about sending an event, not receiving it. + action: send + channel: + $ref: "#/channels/userSignedUp" +``` + +Aside from the issues mentioned above, there may also be infrastructure configuration that is not represented here. For instance, a system may use a read-only channel for receiving messages, a different one for sending them, and an intermediary process that will forward messages from one channel to the other. + +## Table of Contents + + +- [Definitions](#definitions) + - [Server](#definitionsServer) + - [Application](#definitionsApplication) + - [Sender](#definitionsSender) + - [Receiver](#definitionsReceiver) + - [Message](#definitionsMessage) + - [Channel](#definitionsChannel) + - [Protocol](#definitionsProtocol) +- [Specification](#specification) + - [Format](#format) + - [File Structure](#file-structure) + - [Absolute URLs](#absolute-urls) + - [Schema](#schema) + - [AsyncAPI Object](#A2SObject) + - [AsyncAPI Version String](#A2SVersionString) + - [Identifier](#A2SIdString) + - [Info Object](#infoObject) + - [Contact Object](#contactObject) + - [License Object](#licenseObject) + - [Servers Object](#serversObject) + - [Server Object](#serverObject) + - [Server Variable Object](#serverVariableObject) + - [Default Content Type](#defaultContentTypeString) + - [Channels Object](#channelsObject) + - [Channel Object](#channelObject) + - [Operations Object](#operationsObject) + - [Operation Object](#operationObject) + - [Operation Trait Object](#operationTraitObject) + - [Operation Reply Object](#operationReplyObject) + - [Operation Reply Address Object](#operationReplyAddressObject) + - [Message Object](#messageObject) + - [Message Trait Object](#messageTraitObject) + - [Message Example Object](#messageExampleObject) + - [Tags Object](#tagsObject) + - [Tag Object](#tag-object) + - [External Documentation Object](#externalDocumentationObject) + - [Components Object](#componentsObject) + - [Reference Object](#referenceObject) + - [Multi Format Schema Object](#multiFormatSchemaObject) + - [Schema Object](#schemaObject) + - [Security Scheme Object](#securitySchemeObject) + - [OAuth Flows Object](#oauth-flows-object) + - [OAuth Flow Object](#oauth-flow-object) + - [Server Bindings Object](#serverBindingsObject) + - [Parameters Object](#parametersObject) + - [Parameter Object](#parameterObject) + - [Channel Bindings Object](#channelBindingsObject) + - [Operation Bindings Object](#operationBindingsObject) + - [Message Bindings Object](#messageBindingsObject) + - [Correlation ID Object](#correlationIdObject) + - [Specification Extensions](#specificationExtensions) + + + +## Definitions + +### Server +A server MAY be a message broker that is capable of sending and/or receiving between a [sender](#definitionsSender) and [receiver](#definitionsReceiver). A server MAY be a service with WebSocket API that enables message-driven communication between browser-to-server or server-to-server. + +### Application +An application is any kind of computer program or a group of them. It MUST be a [sender](#definitionsSender), a [receiver](#definitionsReceiver), or both. An application MAY be a microservice, IoT device (sensor), mainframe process, message broker, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the [server](#definitionsServer) in order to connect and exchange [messages](#definitionsMessage). + +### Sender +A sender is a type of application, that is sending [messages](#definitionsMessage) to [channels](#definitionsChannel). A sender MAY send to multiple channels depending on the [server](#definitionsServer), protocol, and use-case pattern. + +### Receiver +A receiver is a type of application that is receiving [messages](#definitionsMessage) from [channels](#definitionsChannel). A receiver MAY receive from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. A receiver MAY forward a received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and forwards them. + +### Message +A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MAY contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. + +### Channel +A channel is an addressable component, made available by the [server](#definitionsServer), for the organization of [messages](#definitionsMessage). [Sender](#definitionsSender) applications send messages to channels and [receiver](#definitionsReceiver) applications receive messages from channels. [Servers](#definitionsServer) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#definitionsServer) implementation, the channel MAY be included in the message via protocol-defined headers. + +### Protocol +A protocol is the mechanism (wireline protocol or API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket, Google Pub/Sub, Pulsar. + +### Bindings +A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only. + +## Specification + +### Format + +The files describing the message-driven API in accordance with the AsyncAPI Specification are represented as JSON objects and conform to the JSON standards. +YAML, being a superset of JSON, can be used as well to represent a A2S (AsyncAPI Specification) file. + +For example, if a field is said to have an array value, the JSON array representation will be used: + +```yaml +{ + "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](https://www.yaml.org/spec/1.2/spec.html) is recommended along with some additional constraints: + +- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://www.yaml.org/spec/1.2/spec.html#id2803231) +- Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset + +### File Structure + +An AsyncAPI document MAY be made up of a single document or be divided into multiple, +connected parts at the discretion of the author. In the latter case, [Reference Objects](#referenceObject) are used. + +It is important to note that everything that is defined in an AsyncAPI document MUST be used by the implemented [Application](#definitionsApplication), with the exception of the [Components Object](#componentsObject). Everything that is defined inside the Components Object represents a resource that MAY or MAY NOT be used by the implemented [Application](#definitionsApplication). + +By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. + +### Absolute URLs + +Unless specified otherwise, all properties that are absolute URLs are defined by [RFC3986, section 4.3](https://datatracker.ietf.org/doc/html/rfc3986#section-4.3). + +### Schema + +#### AsyncAPI Object + +This is the root document object for the API specification. +It combines resource listing and API declaration together into one document. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +asyncapi | [AsyncAPI Version String](#A2SVersionString) | **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](#A2SIdString) | Identifier of the [application](#definitionsApplication) the AsyncAPI document is defining. +info | [Info Object](#infoObject) | **REQUIRED.** Provides metadata about the API. The metadata can be used by the clients if needed. +servers | [Servers Object](#serversObject) | Provides connection details of servers. +defaultContentType | [Default Content Type](#defaultContentTypeString) | Default content type to use when encoding/decoding a message's payload. +channels | [Channels Object](#channelsObject) | The channels used by this [application](#definitionsApplication). +operations | [Operations Object](#operationsObject) | The operations this [application](#definitionsApplication) MUST implement. +components | [Components Object](#componentsObject) | An element to hold various reusable objects for the specification. Everything that is defined inside this object represents a resource that MAY or MAY NOT be used in the rest of the document and MAY or MAY NOT be used by the implemented [Application](#definitionsApplication). + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### 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](#definitionsApplication) the AsyncAPI document is defining. It must conform to the URI format, according to [RFC3986](https://tools.ietf.org/html/rfc3986). + +It is RECOMMENDED to use a [URN](https://tools.ietf.org/html/rfc8141) to globally and uniquely identify the application during long periods of time, even after it becomes unavailable or ceases to exist. + +###### Examples + +```json +{ + "id": "urn:example:com:smartylighting:streetlights:server" +} +``` + +```yaml +id: 'urn:example:com:smartylighting:streetlights:server' +``` + +```json +{ + "id": "https://github.com/smartylighting/streetlights-server" +} +``` + +```yaml +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](https://spec.commonmark.org/) can be used for rich text representation. +termsOfService | `string` | A URL to the Terms of Service for the API. This MUST be in the form of an absolute URL. +contact | [Contact Object](#contactObject) | The contact information for the exposed API. +license | [License Object](#licenseObject) | The license information for the exposed API. +tags | [Tags Object](#tagsObject) | A list of tags for application API documentation control. Tags can be used for logical grouping of applications. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation of the exposed API. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Info Object Example: + +```json +{ + "title": "AsyncAPI Sample App", + "version": "1.0.1", + "description": "This is a sample app.", + "termsOfService": "https://asyncapi.org/terms/", + "contact": { + "name": "API Support", + "url": "https://www.asyncapi.org/support", + "email": "support@asyncapi.org" + }, + "license": { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + }, + "externalDocs": { + "description": "Find more info here", + "url": "https://www.asyncapi.org" + }, + "tags": [ + { + "name": "e-commerce" + } + ] +} +``` + +```yaml +title: AsyncAPI Sample App +version: 1.0.1 +description: This is a sample app. +termsOfService: https://asyncapi.org/terms/ +contact: + name: API Support + url: https://www.asyncapi.org/support + email: support@asyncapi.org +license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html +externalDocs: + description: Find more info here + url: https://www.asyncapi.org +tags: + - name: e-commerce +``` + +#### 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. This MUST be in the form of an absolute URL. +email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Contact Object Example: + +```json +{ + "name": "API Support", + "url": "https://www.example.com/support", + "email": "support@example.com" +} +``` + +```yaml +name: API Support +url: https://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. This MUST be in the form of an absolute URL. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### License Object Example: + +```json +{ + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" +} +``` + +```yaml +name: Apache 2.0 +url: https://www.apache.org/licenses/LICENSE-2.0.html +``` + +#### Servers Object + +The Servers Object is a map of [Server Objects](#serverObject). + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +`^[A-Za-z0-9_\-]+$` | [Server Object](#serverObject) \| [Reference Object](#referenceObject) | The definition of a server this application MAY connect to. + +##### Servers Object Example + +```json +{ + "development": { + "host": "localhost:5672", + "description": "Development AMQP broker.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:development", + "description": "This environment is meant for developers to run their own tests." + } + ] + }, + "staging": { + "host": "rabbitmq-staging.in.mycompany.com:5672", + "description": "RabbitMQ broker for the staging environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:staging", + "description": "This environment is a replica of the production environment." + } + ] + }, + "production": { + "host": "rabbitmq.in.mycompany.com:5672", + "description": "RabbitMQ broker for the production environment.", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "tags": [ + { + "name": "env:production", + "description": "This environment is the live environment available for final users." + } + ] + } +} +``` + +```yaml +development: + host: localhost:5672 + description: Development AMQP broker. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:development" + description: "This environment is meant for developers to run their own tests." +staging: + host: rabbitmq-staging.in.mycompany.com:5672 + description: RabbitMQ broker for the staging environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:staging" + description: "This environment is a replica of the production environment." +production: + host: rabbitmq.in.mycompany.com:5672 + description: RabbitMQ broker for the production environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:production" + description: "This environment is the live environment available for final users." +``` + + +#### Server Object + +An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +host | `string` | **REQUIRED**. The server host name. It MAY include the port. This field supports [Server Variables](#serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. +protocol | `string` | **REQUIRED**. The protocol this server supports for connection. +protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. +pathname | `string` | The path to a resource in the host. This field supports [Server Variables](#serverObjectVariables). Variable substitutions will be made when a variable is named in `{`braces`}`. +description | `string` | An optional string describing the server. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +title | `string` | A human-friendly title for the server. +summary | `string` | A short summary of the server. +variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's `host` and `pathname` template. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | A declaration of which security schemes can be used with this server. The list of values includes alternative [security scheme objects](#securitySchemeObject) that can be used. Only one of the security scheme objects need to be satisfied to authorize a connection or operation. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this server. +bindings | [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server. + +##### Server Object Example + +A single server would be described as: + +```json +{ + "host": "kafka.in.mycompany.com:9092", + "description": "Production Kafka broker.", + "protocol": "kafka", + "protocolVersion": "3.2" +} +``` + +```yaml +host: kafka.in.mycompany.com:9092 +description: Production Kafka broker. +protocol: kafka +protocolVersion: '3.2' +``` + +An example of a server that has a `pathname`: + +```json +{ + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/production", + "protocol": "amqp", + "description": "Production RabbitMQ broker (uses the `production` vhost)." +} +``` + +```yaml +host: rabbitmq.in.mycompany.com:5672 +pathname: /production +protocol: amqp +description: Production RabbitMQ broker (uses the `production` vhost). +``` + +#### Server Variable Object + +An object representing a Server Variable for server URL template substitution. + +##### 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](https://spec.commonmark.org/) 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](#specificationExtensions). + +##### Server Variable Object Example + +```json +{ + "host": "rabbitmq.in.mycompany.com:5672", + "pathname": "/{env}", + "protocol": "amqp", + "description": "RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`.", + "variables": { + "env": { + "description": "Environment to connect to. It can be either `production` or `staging`.", + "enum": [ + "production", + "staging" + ] + } + } +} +``` + +```yaml +host: 'rabbitmq.in.mycompany.com:5672' +pathname: '/{env}' +protocol: amqp +description: RabbitMQ broker. Use the `env` variable to point to either `production` or `staging`. +variables: + env: + description: Environment to connect to. It can be either `production` or `staging`. + enum: + - production + - staging +``` + + +#### Default Content Type + +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](#messageObjectContentType) 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 + +```json +{ + "defaultContentType": "application/json" +} +``` + +```yaml +defaultContentType: application/json +``` + + + + + + +#### Channels Object + +An object containing all the [Channel Object](#channelObject) definitions the [Application](#definitionsApplication) MUST use during runtime. + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +{channelId} | [Channel Object](#channelObject) \| [Reference Object](#referenceObject) | An identifier for the described channel. The `channelId` value is **case-sensitive**. Tools and libraries MAY use the `channelId` to uniquely identify a channel, therefore, it is RECOMMENDED to follow common programming naming conventions. + +##### Channels Object Example + +```json +{ + "userSignedUp": { + "address": "user.signedup", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + } + } + } +} +``` + +```yaml +userSignedUp: + address: 'user.signedup' + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' +``` + + + + +#### Channel Object + +Describes a shared communication channel. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channelBindingsObject) to define them. +messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#messageObject) defined in this map.** +title | `string` | A human-friendly title for the channel. +summary | `string` | A short summary of the channel. +description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +servers | [[Reference Object](#referenceObject)] | An array of `$ref` pointers to the definition of the servers in which this channel is available. If the channel is located in the [root Channels Object](#channelsObject), it MUST point to a subset of server definitions located in the [root Servers Object](#serversObject), and MUST NOT point to a subset of server definitions located in the [Components Object](#componentsObject) or anywhere else. If the channel is located in the [Components Object](#componentsObject), it MAY point to a [Server Objects](#serverObject) in any location. If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#serverObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](#channelAddressExpressions). +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this channel. +bindings | [Channel Bindings Object](#channelBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. + + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Channel Object Example + +```json +{ + "address": "users.{userId}", + "title": "Users channel", + "description": "This channel is used to exchange messages about user events.", + "messages": { + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" + } + }, + "parameters": { + "userId": { + "$ref": "#/components/parameters/userId" + } + }, + "servers": [ + { "$ref": "#/servers/rabbitmqInProd" }, + { "$ref": "#/servers/rabbitmqInStaging" } + ], + "bindings": { + "amqp": { + "is": "queue", + "queue": { + "exclusive": true + } + } + }, + "tags": [{ + "name": "user", + "description": "User-related messages" + }], + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" + } +} +``` + +```yaml +address: 'users.{userId}' +title: Users channel +description: This channel is used to exchange messages about user events. +messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' +parameters: + userId: + $ref: '#/components/parameters/userId' +servers: + - $ref: '#/servers/rabbitmqInProd' + - $ref: '#/servers/rabbitmqInStaging' +bindings: + amqp: + is: queue + queue: + exclusive: true +tags: + - name: user + description: User-related messages +externalDocs: + description: 'Find more info here' + url: 'https://example.com' +``` + + + + + +#### Channel Address Expressions + +Channel addresses MAY contain expressions that can be used to define dynamic values. + +Expressions MUST be composed by a name enclosed in curly braces (`{` and `}`). E.g., `{userId}`. + + + + + +#### Messages Object + +Describes a map of messages included in a channel. + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +`{messageId}` | [Message Object](#messageObject) \| [Reference Object](#referenceObject) | The key represents the message identifier. The `messageId` value is **case-sensitive**. Tools and libraries MAY use the `messageId` value to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. + +##### Messages Object Example + +```json +{ + "userSignedUp": { + "$ref": "#/components/messages/userSignedUp" + }, + "userCompletedOrder": { + "$ref": "#/components/messages/userCompletedOrder" + } +} +``` + +```yaml +userSignedUp: + $ref: '#/components/messages/userSignedUp' +userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' +``` + + + +#### Operations Object + +Holds a dictionary with all the [operations](#operationObject) this application MUST implement. + +> If you're looking for a place to define operations that MAY or MAY NOT be implemented by the application, consider defining them in [`components/operations`](#componentsOperations). + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +{operationId} | [Operation Object](#operationObject) \| [Reference Object](#referenceObject) | The operation this application MUST implement. The field name (`operationId`) MUST be a string used to identify the operation in the document where it is defined, and its value is **case-sensitive**. Tools and libraries MAY use the `operationId` to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. + +##### Operations Object Example + +```json +{ + "onUserSignUp": { + "title": "User sign up", + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { "$ref": "#/components/operationTraits/kafka" } + ] + } +} +``` + +```yaml +onUserSignUp: + title: User sign up + summary: Action to sign a user up. + description: A longer description + channel: + $ref: '#/channels/userSignup' + action: send + tags: + - name: user + - name: signup + - name: register + bindings: + amqp: + ack: false + traits: + - $ref: '#/components/operationTraits/kafka' +``` + + +#### Operation Object + +Describes a specific operation. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +action | `"send"` | `"receive"` | **Required**. Use `send` when it's expected that the application will send a message to the given [`channel`](#operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#operationObjectChannel). +channel | [Reference Object](#referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. If the operation is located in the [root Operations Object](#operationsObject), it MUST point to a channel definition located in the [root Channels Object](#channelsObject), and MUST NOT point to a channel definition located in the [Components Object](#componentsObject) or anywhere else. If the operation is located in the [Components Object](#componentsObject), it MAY point to a [Channel Object](#channelObject) in any location. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +title | `string` | A human-friendly title for the operation. +summary | `string` | A short summary of what the operation is about. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#serverObjectSecurity) also applies, it MUST also be satisfied. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation. +bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. +traits | [[Operation Trait Object](#operationTraitObject) | [Reference Object](#referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged using [traits merge mechanism](#traits-merge-mechanism). The resulting object MUST be a valid [Operation Object](#operationObject). +messages | [[Reference Object](#referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#messageObject) that can be processed by this operation. It MUST contain a subset of the messages defined in the [channel referenced in this operation](#operationObjectChannel), and MUST NOT point to a subset of message definitions located in the [Messages Object](#componentsMessages) in the [Components Object](#componentsObject) or anywhere else. **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#messageObject) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain [Message Objects](#messageObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +reply | [Operation Reply Object](#operationReplyObject) | [Reference Object](#referenceObject) | The definition of the reply in a request-reply operation. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Operation Object Example + +```json +{ + "title": "User sign up", + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "security": [ + { + "petstore_auth": [ + "write:pets", + "read:pets" + ] + } + ], + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { "$ref": "#/components/operationTraits/kafka" } + ], + "messages": [ + { "$ref": "/components/messages/userSignedUp" } + ], + "reply": { + "address": { + "location": "$message.header#/replyTo" + }, + "channel": { + "$ref": "#/channels/userSignupReply" + }, + "messages": [ + { "$ref": "/components/messages/userSignedUpReply" } + ], + } +} +``` + +```yaml +title: User sign up +summary: Action to sign a user up. +description: A longer description +channel: + $ref: '#/channels/userSignup' +action: send +security: + - petstore_auth: + - write:pets + - read:pets +tags: + - name: user + - name: signup + - name: register +bindings: + amqp: + ack: false +traits: + - $ref: "#/components/operationTraits/kafka" +messages: + - $ref: '#/components/messages/userSignedUp' +reply: + address: + location: '$message.header#/replyTo' + channel: + $ref: '#/channels/userSignupReply' + messages: + - $ref: '#/components/messages/userSignedUpReply' +``` + + + + +#### Operation Trait Object + +Describes a trait that MAY be applied to an [Operation Object](#operationObject). This object MAY contain any property from the [Operation Object](#operationObject), except the `action`, `channel`, `messages` and `traits` ones. + +If you're looking to apply traits to a message, see the [Message Trait Object](#messageTraitObject). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +title | `string` | A human-friendly title for the operation. +summary | `string` | A short summary of what the operation is about. +description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)]| A declaration of which security schemes are associated with this operation. Only one of the [security scheme objects](#securitySchemeObject) MUST be satisfied to authorize an operation. In cases where [Server Security](#serverObjectSecurity) also applies, it MUST also be satisfied. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of operations. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation. +bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Operation Trait Object Example + +```json +{ + "bindings": { + "amqp": { + "ack": false + } + } +} +``` + +```yaml +bindings: + amqp: + ack: false +``` + + + + +#### Operation Reply Object + +Describes the reply part that MAY be applied to an Operation Object. If an operation implements the request/reply pattern, the reply object represents the response message. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +address | [Operation Reply Address Object](#operationReplyAddressObject) | [Reference Object](#referenceObject) | Definition of the address that implementations MUST use for the reply. +channel | [Reference Object](#referenceObject) | A `$ref` pointer to the definition of the channel in which this operation is performed. When [address](#operationReplyAddressObject) is specified, the [`address` property](#channelObjectAddress) of the channel referenced by this property MUST be either `null` or not defined. If the operation reply is located inside a [root Operation Object](#operationObject), it MUST point to a channel definition located in the [root Channels Object](#channelsObject), and MUST NOT point to a channel definition located in the [Components Object](#componentsObject) or anywhere else. If the operation reply is located inside an [Operation Object] in the [Components Object](#componentsObject) or in the [Replies Object](#componentsReplies) in the [Components Object](#componentsObject), it MAY point to a [Channel Object](#channelObject) in any location. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +messages | [[Reference Object](#referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#messageObject) that can be processed by this operation as reply. It MUST contain a subset of the messages defined in the [channel referenced in this operation reply](#operationObjectChannel), and MUST NOT point to a subset of message definitions located in the [Components Object](#componentsObject) or anywhere else. **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#messageObject) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain [Message Objects](#messageObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### Operation Reply Address Object + +An object that specifies where an operation has to send the reply. + +For specifying and computing the location of a reply address, a [runtime expression](#runtimeExpression) is used. + + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- +description | `string` | An optional description of the address. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +location | `string` | **REQUIRED.** A [runtime expression](#runtimeExpression) that specifies the location of the reply address. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Examples + +```json +{ + "description": "Consumer inbox", + "location": "$message.header#/replyTo" +} +``` + +```yaml +description: Consumer Inbox +location: $message.header#/replyTo +``` + + +#### Parameters Object + +Describes a map of parameters included in a channel address. + +This map MUST contain all the parameters used in the parent channel address. + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +`^[A-Za-z0-9_\-]+$` | [Parameter Object](#parameterObject) | [Reference Object](#referenceObject) | The key represents the name of the parameter. It MUST match the parameter name used in the parent channel address. + +##### Parameters Object Example + +```json +{ + "address": "user/{userId}/signedup", + "parameters": { + "userId": { + "description": "Id of the user." + } + } +} +``` + +```yaml +address: user/{userId}/signedup +parameters: + userId: + description: Id of the user. +``` + + + + + +#### Parameter Object + +Describes a parameter included in a channel address. + +##### 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 parameter. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +examples | [`string`] | An array of examples of the parameter value. +location | `string` | A [runtime expression](#runtimeExpression) that specifies the location of the parameter value. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Parameter Object Example + +```json +{ + "address": "user/{userId}/signedup", + "parameters": { + "userId": { + "description": "Id of the user.", + "location": "$message.payload#/user/id" + } + } +} +``` + +```yaml +address: user/{userId}/signedup +parameters: + userId: + description: Id of the user. + location: $message.payload#/user/id +``` + + + + +#### Server Bindings Object + +Map describing protocol-specific definitions for a server. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Server Binding](https://github.com/asyncapi/bindings/blob/master/http#server) | Protocol-specific information for an HTTP server. +`ws` | [WebSockets Server Binding](https://github.com/asyncapi/bindings/blob/master/websockets#server) | Protocol-specific information for a WebSockets server. +`kafka` | [Kafka Server Binding](https://github.com/asyncapi/bindings/blob/master/kafka#server) | Protocol-specific information for a Kafka server. +`anypointmq` | [Anypoint MQ Server Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq#server) | Protocol-specific information for an Anypoint MQ server. +`amqp` | [AMQP Server Binding](https://github.com/asyncapi/bindings/blob/master/amqp#server) | Protocol-specific information for an AMQP 0-9-1 server. +`amqp1` | [AMQP 1.0 Server Binding](https://github.com/asyncapi/bindings/blob/master/amqp1#server) | Protocol-specific information for an AMQP 1.0 server. +`mqtt` | [MQTT Server Binding](https://github.com/asyncapi/bindings/blob/master/mqtt#server) | Protocol-specific information for an MQTT server. +`mqtt5` | [MQTT 5 Server Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5#server) | Protocol-specific information for an MQTT 5 server. +`nats` | [NATS Server Binding](https://github.com/asyncapi/bindings/blob/master/nats#server) | Protocol-specific information for a NATS server. +`jms` | [JMS Server Binding](https://github.com/asyncapi/bindings/blob/master/jms#server) | Protocol-specific information for a JMS server. +`sns` | [SNS Server Binding](https://github.com/asyncapi/bindings/blob/master/sns#server) | Protocol-specific information for an SNS server. +`solace` | [Solace Server Binding](https://github.com/asyncapi/bindings/blob/master/solace#server) | Protocol-specific information for a Solace server. +`sqs` | [SQS Server Binding](https://github.com/asyncapi/bindings/blob/master/sqs#server) | Protocol-specific information for an SQS server. +`stomp` | [STOMP Server Binding](https://github.com/asyncapi/bindings/blob/master/stomp#server) | Protocol-specific information for a STOMP server. +`redis` | [Redis Server Binding](https://github.com/asyncapi/bindings/blob/master/redis#server) | Protocol-specific information for a Redis server. +`mercure` | [Mercure Server Binding](https://github.com/asyncapi/bindings/blob/master/mercure#server) | Protocol-specific information for a Mercure server. +`ibmmq` | [IBM MQ Server Binding](https://github.com/asyncapi/bindings/blob/master/ibmmq#server-binding-object) | Protocol-specific information for an IBM MQ server. +`googlepubsub` | [Google Cloud Pub/Sub Server Binding](https://github.com/asyncapi/bindings/blob/master/googlepubsub#server) | Protocol-specific information for a Google Cloud Pub/Sub server. +`pulsar` | [Pulsar Server Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#server-binding-object) | Protocol-specific information for a Pulsar server. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + + + +#### Channel Bindings Object + +Map describing protocol-specific definitions for a channel. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Channel Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#channel) | Protocol-specific information for an HTTP channel. +`ws` | [WebSockets Channel Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#channel) | Protocol-specific information for a WebSockets channel. +`kafka` | [Kafka Channel Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#channel) | Protocol-specific information for a Kafka channel. +`anypointmq` | [Anypoint MQ Channel Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#channel) | Protocol-specific information for an Anypoint MQ channel. +`amqp` | [AMQP Channel Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#channel) | Protocol-specific information for an AMQP 0-9-1 channel. +`amqp1` | [AMQP 1.0 Channel Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#channel) | Protocol-specific information for an AMQP 1.0 channel. +`mqtt` | [MQTT Channel Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#channel) | Protocol-specific information for an MQTT channel. +`mqtt5` | [MQTT 5 Channel Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5#channel) | Protocol-specific information for an MQTT 5 channel. +`nats` | [NATS Channel Binding](https://github.com/asyncapi/bindings/blob/master/nats/README.md#channel) | Protocol-specific information for a NATS channel. +`jms` | [JMS Channel Binding](https://github.com/asyncapi/bindings/blob/master/jms/README.md#channel) | Protocol-specific information for a JMS channel. +`sns` | [SNS Channel Binding](https://github.com/asyncapi/bindings/blob/master/sns/README.md#channel) | Protocol-specific information for an SNS channel. +`solace` | [Solace Channel Binding](https://github.com/asyncapi/bindings/blob/master/solace#channel) | Protocol-specific information for a Solace channel. +`sqs` | [SQS Channel Binding](https://github.com/asyncapi/bindings/blob/master/sqs/README.md#channel) | Protocol-specific information for an SQS channel. +`stomp` | [STOMP Channel Binding](https://github.com/asyncapi/bindings/blob/master/stomp/README.md#channel) | Protocol-specific information for a STOMP channel. +`redis` | [Redis Channel Binding](https://github.com/asyncapi/bindings/blob/master/redis#channel) | Protocol-specific information for a Redis channel. +`mercure` | [Mercure Channel Binding](https://github.com/asyncapi/bindings/blob/master/mercure#channel) | Protocol-specific information for a Mercure channel. +`ibmmq` | [IBM MQ Channel Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#channel-binding-object) | Protocol-specific information for an IBM MQ channel. +`googlepubsub` | [Google Cloud Pub/Sub Channel Binding](https://github.com/asyncapi/bindings/tree/master/googlepubsub#channel) | Protocol-specific information for a Google Cloud Pub/Sub channel. +`pulsar` | [Pulsar Channel Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#channel-binding-object) | Protocol-specific information for a Pulsar channel. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + + + +#### Operation Bindings Object + +Map describing protocol-specific definitions for an operation. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Operation Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#operation) | Protocol-specific information for an HTTP operation. +`ws` | [WebSockets Operation Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#operation) | Protocol-specific information for a WebSockets operation. +`kafka` | [Kafka Operation Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#operation) | Protocol-specific information for a Kafka operation. +`anypointmq` | [Anypoint MQ Operation Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#operation) | Protocol-specific information for an Anypoint MQ operation. +`amqp` | [AMQP Operation Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#operation) | Protocol-specific information for an AMQP 0-9-1 operation. +`amqp1` | [AMQP 1.0 Operation Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#operation) | Protocol-specific information for an AMQP 1.0 operation. +`mqtt` | [MQTT Operation Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#operation) | Protocol-specific information for an MQTT operation. +`mqtt5` | [MQTT 5 Operation Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5/README.md#operation) | Protocol-specific information for an MQTT 5 operation. +`nats` | [NATS Operation Binding](https://github.com/asyncapi/bindings/blob/master/nats/README.md#operation) | Protocol-specific information for a NATS operation. +`jms` | [JMS Operation Binding](https://github.com/asyncapi/bindings/blob/master/jms/README.md#operation) | Protocol-specific information for a JMS operation. +`sns` | [SNS Operation Binding](https://github.com/asyncapi/bindings/blob/master/sns/README.md#operation) | Protocol-specific information for an SNS operation. +`solace` | [Solace Operation Binding](https://github.com/asyncapi/bindings/blob/master/solace#operation) | Protocol-specific information for a Solace operation. +`sqs` | [SQS Operation Binding](https://github.com/asyncapi/bindings/blob/master/sqs/README.md#operation) | Protocol-specific information for an SQS operation. +`stomp` | [STOMP Operation Binding](https://github.com/asyncapi/bindings/blob/master/stomp/README.md#operation) | Protocol-specific information for a STOMP operation. +`redis` | [Redis Operation Binding](https://github.com/asyncapi/bindings/blob/master/redis#operation) | Protocol-specific information for a Redis operation. +`mercure` | [Mercure Operation Binding](https://github.com/asyncapi/bindings/blob/master/mercure#operation) | Protocol-specific information for a Mercure operation. +`googlepubsub` | [Google Cloud Pub/Sub Operation Binding](https://github.com/asyncapi/bindings/blob/master/googlepubsub#operation) | Protocol-specific information for a Google Cloud Pub/Sub operation. +`ibmmq` | [IBM MQ Operation Binding](https://github.com/asyncapi/bindings/blob/master/ibmmq#operation-binding-object) | Protocol-specific information for an IBM MQ operation. +`pulsar` | [Pulsar Operation Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#operation-binding-fields) | Protocol-specific information for a Pulsar operation. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + + + + +#### Message Bindings Object + +Map describing protocol-specific definitions for a message. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +`http` | [HTTP Message Binding](https://github.com/asyncapi/bindings/blob/master/http/README.md#message) | Protocol-specific information for an HTTP message, i.e., a request or a response. +`ws` | [WebSockets Message Binding](https://github.com/asyncapi/bindings/blob/master/websockets/README.md#message) | Protocol-specific information for a WebSockets message. +`kafka` | [Kafka Message Binding](https://github.com/asyncapi/bindings/blob/master/kafka/README.md#message) | Protocol-specific information for a Kafka message. +`anypointmq` | [Anypoint MQ Message Binding](https://github.com/asyncapi/bindings/blob/master/anypointmq/README.md#message) | Protocol-specific information for an Anypoint MQ message. +`amqp` | [AMQP Message Binding](https://github.com/asyncapi/bindings/blob/master/amqp/README.md#message) | Protocol-specific information for an AMQP 0-9-1 message. +`amqp1` | [AMQP 1.0 Message Binding](https://github.com/asyncapi/bindings/blob/master/amqp1/README.md#message) | Protocol-specific information for an AMQP 1.0 message. +`mqtt` | [MQTT Message Binding](https://github.com/asyncapi/bindings/blob/master/mqtt/README.md#message) | Protocol-specific information for an MQTT message. +`mqtt5` | [MQTT 5 Message Binding](https://github.com/asyncapi/bindings/blob/master/mqtt5/README.md#message) | Protocol-specific information for an MQTT 5 message. +`nats` | [NATS Message Binding](https://github.com/asyncapi/bindings/blob/master/nats/README.md#message) | Protocol-specific information for a NATS message. +`jms` | [JMS Message Binding](https://github.com/asyncapi/bindings/blob/master/jms/README.md#message) | Protocol-specific information for a JMS message. +`sns` | [SNS Message Binding](https://github.com/asyncapi/bindings/blob/master/sns/README.md#message) | Protocol-specific information for an SNS message. +`solace` | [Solace Server Binding](https://github.com/asyncapi/bindings/blob/master/solace#message) | Protocol-specific information for a Solace message. +`sqs` | [SQS Message Binding](https://github.com/asyncapi/bindings/blob/master/sqs/README.md#message) | Protocol-specific information for an SQS message. +`stomp` | [STOMP Message Binding](https://github.com/asyncapi/bindings/blob/master/stomp/README.md#message) | Protocol-specific information for a STOMP message. +`redis` | [Redis Message Binding](https://github.com/asyncapi/bindings/blob/master/redis#message) | Protocol-specific information for a Redis message. +`mercure` | [Mercure Message Binding](https://github.com/asyncapi/bindings/blob/master/mercure#message) | Protocol-specific information for a Mercure message. +`ibmmq` | [IBM MQ Message Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#message-binding-object) | Protocol-specific information for an IBM MQ message. +`googlepubsub` | [Google Cloud Pub/Sub Message Binding](https://github.com/asyncapi/bindings/tree/master/googlepubsub#message) | Protocol-specific information for a Google Cloud Pub/Sub message. +`pulsar` | [Pulsar Message Binding](https://github.com/asyncapi/bindings/tree/master/pulsar#message-binding-fields) | Protocol-specific information for a Pulsar message. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + + + + + + + +#### Message Object + +Describes a message received on a given channel and operation. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +headers | [Multi Format Schema Object](#multiFormatSchemaObject) | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be a map of key-value pairs. It **MUST NOT** define the protocol headers. If this is a [Schema Object](#schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#A2SVersionString). +payload | [Multi Format Schema Object](#multiFormatSchemaObject) | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Definition of the message payload. If this is a [Schema Object](#schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#A2SVersionString). +correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. +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](#defaultContentTypeString) 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](https://spec.commonmark.org/) can be used for rich text representation. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of messages. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this message. +bindings | [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. +examples | [[Message Example Object](#messageExampleObject)] | List of examples. +traits | [[Message Trait Object](#messageTraitObject) | [Reference Object](#referenceObject)] | A list of traits to apply to the message object. Traits MUST be merged using [traits merge mechanism](#traits-merge-mechanism). The resulting object MUST be a valid [Message Object](#messageObject). + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Message Object Example + +```json +{ + "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": { + "type": "object", + "properties": { + "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" + }, + "traits": [ + { "$ref": "#/components/messageTraits/commonHeaders" } + ], + "examples": [ + { + "name": "SimpleSignup", + "summary": "A simple UserSignup example message", + "headers": { + "correlationId": "my-correlation-id", + "applicationInstanceId": "myInstanceId" + }, + "payload": { + "user": { + "someUserKey": "someUserValue" + }, + "signup": { + "someSignupKey": "someSignupValue" + } + } + } + ] +} +``` + +```yaml +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: + type: object + properties: + 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 +traits: + - $ref: "#/components/messageTraits/commonHeaders" +examples: + - name: SimpleSignup + summary: A simple UserSignup example message + headers: + correlationId: my-correlation-id + applicationInstanceId: myInstanceId + payload: + user: + someUserKey: someUserValue + signup: + someSignupKey: someSignupValue +``` + +Example using Avro to define the payload: + +```json +{ + "name": "UserSignup", + "title": "User signup", + "summary": "Action to sign a user up.", + "description": "A longer description", + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "payload": { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "schema": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } +} +``` + +```yaml +name: UserSignup +title: User signup +summary: Action to sign a user up. +description: A longer description +tags: + - name: user + - name: signup + - name: register +payload: + schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' + schema: + $ref: 'path/to/user-create.avsc/#UserCreate' +``` + + + + + + + +#### Message Trait Object + +Describes a trait that MAY be applied to a [Message Object](#messageObject). This object MAY contain any property from the [Message Object](#messageObject), except `payload` and `traits`. + +If you're looking to apply traits to an operation, see the [Operation Trait Object](#operationTraitObject). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +headers | [Multi Format Schema Object](#multiFormatSchemaObject) | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be a map of key-value pairs. It **MUST NOT** define the protocol headers. If this is a [Schema Object](#schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#A2SVersionString). +correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. +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](#defaultContentTypeString) 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](https://spec.commonmark.org/) can be used for rich text representation. +tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of messages. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this message. +bindings | [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. +examples | [[Message Example Object](#messageExampleObject)] | List of examples. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Message Trait Object Example + +```json +{ + "contentType": "application/json" +} +``` + +```yaml +contentType: application/json +``` + +#### Message Example Object + +Message Example Object represents an example of a [Message Object](#messageObject) and MUST contain either **headers** and/or **payload** fields. + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +headers | `Map[string, any]` | The value of this field MUST validate against the [Message Object's headers](#messageObjectHeaders) field. +payload | `Map[string, any]` | The value of this field MUST validate against the [Message Object's payload](#messageObjectPayload) field. +name | `string` | A machine-friendly name. +summary | `string` | A short summary of what the example is about. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Message Example Object Example + +```json +{ + "name": "SimpleSignup", + "summary": "A simple UserSignup example message", + "headers": { + "correlationId": "my-correlation-id", + "applicationInstanceId": "myInstanceId" + }, + "payload": { + "user": { + "someUserKey": "someUserValue" + }, + "signup": { + "someSignupKey": "someSignupValue" + } + } +} +``` + +```yaml +name: SimpleSignup +summary: A simple UserSignup example message +headers: + correlationId: my-correlation-id + applicationInstanceId: myInstanceId +payload: + user: + someUserKey: someUserValue + signup: + someSignupKey: someSignupValue +``` + +#### Tags Object + +A Tags object is a list of [Tag Objects](#tagObject). An [Tag Object](#tagObject) in a list can be referenced by [Reference Object](#referenceObject). + +#### Tag Object + +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](https://spec.commonmark.org/) can be used for rich text representation. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this tag. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Tag Object Example + +```json +{ + "name": "user", + "description": "User-related messages" +} +``` + +```yaml +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](https://spec.commonmark.org/) can be used for rich text representation. +url | `string` | **REQUIRED.** The URL for the target documentation. This MUST be in the form of an absolute URL. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### External Documentation Object Example + +```json +{ + "description": "Find more info here", + "url": "https://example.com" +} +``` + +```yaml +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](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules. A JSON Reference SHALL only be used to refer to a schema that is formatted in either JSON or YAML. In the case of a YAML-formatted Schema, the JSON Reference SHALL be applied to the JSON representation of that schema. The JSON representation SHALL be made by applying the conversion described [here](#format). + +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 + +```json +{ + "$ref": "#/components/schemas/Pet" +} +``` + +```yaml + $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`, [Multi Format Schema Object](#multiFormatSchemaObject) \| [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Object](#schemaObject). If this is a [Schema Object](#schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#A2SVersionString). + servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject). + channels | Map[`string`, [Channel Object](#channelObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Objects](#channelObject). + operations | Map[`string`, [Operation Object](#operationObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Objects](#operationObject). + messages | Map[`string`, [Message Object](#messageObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Objects](#messageObject). + securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). + serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). + parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). + correlationIds | Map[`string`, [Correlation ID Object](#correlationIdObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Correlation ID Objects](#correlationIdObject). +replies | Map[`string`, [Operation Reply Object](#operationReplyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Reply Objects](#operationReplyObject). + replyAddresses | Map[`string`, [Operation Reply Address Object](#operationReplyAddressObject) | [Reference Object](#referenceObject)] | An object to hold reusable [Operation Reply Address Objects](#operationReplyAddressObject). + externalDocs | Map[`string`, [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [External Documentation Objects](#externalDocumentationObject). + tags | Map[`string`, [Tag Object](#tagObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Tag Objects](#tagObject). + operationTraits | Map[`string`, [Operation Trait Object](#operationTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Trait Objects](#operationTraitObject). + messageTraits | Map[`string`, [Message Trait Object](#messageTraitObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Trait Objects](#messageTraitObject). + serverBindings | Map[`string`, [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Bindings Objects](#serverBindingsObject). + channelBindings | Map[`string`, [Channel Bindings Object](#channelBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Bindings Objects](#channelBindingsObject). + operationBindings | Map[`string`, [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Bindings Objects](#operationBindingsObject). + messageBindings | Map[`string`, [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Bindings Objects](#messageBindingsObject). + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +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 + +```json +{ + "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" + } + } + }, + "AvroExample": { + "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", + "schema": { + "$ref": "path/to/user-create.avsc#/UserCreate" + } + } + }, + "servers": { + "development": { + "host": "{stage}.in.mycompany.com:{port}", + "description": "RabbitMQ broker", + "protocol": "amqp", + "protocolVersion": "0-9-1", + "variables": { + "stage": { + "$ref": "#/components/serverVariables/stage" + }, + "port": { + "$ref": "#/components/serverVariables/port" + } + } + } + }, + "serverVariables": { + "stage": { + "default": "demo", + "description": "This value is assigned by the service provider, in this example `mycompany.com`" + }, + "port": { + "enum": ["5671", "5672"], + "default": "5672" + } + }, + "channels": { + "user/signedup": { + "subscribe": { + "message": { + "$ref": "#/components/messages/userSignUp" + } + } + } + }, + "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": { + "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": { + "description": "Id of the user." + } + }, + "correlationIds": { + "default": { + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" + } + }, + "messageTraits": { + "commonHeaders": { + "headers": { + "type": "object", + "properties": { + "my-app-header": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + } + } + } + } + } +} +``` + +```yaml +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 + AvroExample: + schemaFormat: application/vnd.apache.avro+json;version=1.9.0 + schema: + $ref: 'path/to/user-create.avsc/#UserCreate' + servers: + development: + host: "{stage}.in.mycompany.com:{port}" + description: RabbitMQ broker + protocol: amqp + protocolVersion: 0-9-1 + variables: + stage: + $ref: "#/components/serverVariables/stage" + port: + $ref: "#/components/serverVariables/port" + serverVariables: + stage: + default: demo + description: This value is assigned by the service provider, in this example `mycompany.com` + port: + enum: ["5671", "5672"] + default: "5672" + channels: + user/signedup: + subscribe: + message: + $ref: "#/components/messages/userSignUp" + 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: + 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: + description: Id of the user. + correlationIds: + default: + description: Default Correlation ID + location: $message.header#/correlationId + messageTraits: + commonHeaders: + headers: + type: object + properties: + my-app-header: + type: integer + minimum: 0 + maximum: 100 +``` + +#### Multi Format Schema Object + +The Multi Format Schema Object represents a schema definition. It differs from the [Schema Object](#schemaObject) in that it supports multiple schema formats or languages (e.g., JSON Schema, Avro, etc.). + +##### Fixed Fields + +Field Name | Type | Description +---|:---:|--- +schemaFormat | `string` | **Required**. A string containing the name of the schema format that is used to define the information. If `schemaFormat` is missing, it MUST default to `application/vnd.aai.asyncapi+json;version={{asyncapi}}` where `{{asyncapi}}` matches the [AsyncAPI Version String](#A2SVersionString). In such a case, this would make the Multi Format Schema Object equivalent to the [Schema Object](#schemaObject). When using [Reference Object](#referenceObject) within the schema, the `schemaFormat` of the resource being referenced MUST match the `schemaFormat` of the schema that contains the initial reference. For example, if you reference Avro `schema`, then `schemaFormat` of referencing resource and the resource being reference MUST match.
Check out the [supported schema formats table](#multiFormatSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#multiFormatSchemaFormatTable).
When using [Reference Objects](#referenceObject) within the schema, the `schemaFormat` of the referenced resource MUST match the `schemaFormat` of the schema containing the reference. +schema | `any` | **Required**. Definition of the message payload. It can be of any type but defaults to [Schema Object](#schemaObject). It MUST match the schema format defined in [`schemaFormat`](#multiFormatSchemaObjectSchemaFormat), including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Schema formats table + +The following table contains a set of values that every implementation MUST support. + +Name | Allowed values | Notes +---|:---:|--- +[AsyncAPI 3.0.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided. +[JSON Schema Draft 07](https://json-schema.org/specification-links.html#draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | + +The following table contains a set of values that every implementation is RECOMMENDED to support. + +Name | Allowed values | Notes +---|:---:|--- +[Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` | +[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | +[RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` | +[Protocol Buffers](https://protobuf.dev/) | `application/vnd.google.protobuf;version=2`, `application/vnd.google.protobuf;version=3` | + + +#### Schema Object + +The Schema Object allows the definition of input and output data types. +These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/). The empty schema (which allows any instance to validate) MAY be represented by the `boolean` value `true` and a schema which allows no instance to validate MAY be represented by the `boolean` value `false`. + +Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-handrews-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01). +Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. For other formats (e.g., Avro, RAML, etc) see [Multi Format Schema Object](#multiFormatSchemaObject). + +##### Properties + +The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such, any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to: + +- title +- type +- required +- multipleOf +- maximum +- exclusiveMaximum +- minimum +- exclusiveMinimum +- maxLength +- minLength +- pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#sec-7.8.5) dialect) +- maxItems +- minItems +- uniqueItems +- maxProperties +- minProperties +- enum +- const +- examples +- if / then / else +- readOnly +- writeOnly +- properties +- patternProperties +- additionalProperties +- additionalItems +- items +- propertyNames +- contains +- allOf +- oneOf +- anyOf +- not + +The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. + +- description - [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +- format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. +- default - Use it to specify that property has a predefined value if no other value is present. 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](#referenceObject) can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the `$ref` keyword MUST follow the behavior described by [Reference Object](#referenceObject) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#ref). + +In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#schemaComposition) for more details. +externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this schema. + deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +###### 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 two ways to define the value of a discriminator for an inheriting instance. + +- Use the schema's name. +- Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. + +As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. + +##### Schema Object Examples + +###### Primitive Sample + +```json +{ + "type": "string", + "format": "email" +} +``` + +```yaml +type: string +format: email +``` + +###### Simple Model + +```json +{ + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + }, + "address": { + "$ref": "#/components/schemas/Address" + }, + "age": { + "type": "integer", + "format": "int32", + "minimum": 0 + } + } +} +``` + +```yaml +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: + +```json +{ + "type": "object", + "additionalProperties": { + "type": "string" + } +} +``` + +```yaml +type: object +additionalProperties: + type: string +``` + +For a string to model mapping: + +```json +{ + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/ComplexModel" + } +} +``` + +```yaml +type: object +additionalProperties: + $ref: '#/components/schemas/ComplexModel' +``` + +###### Model with Example + +```json +{ + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "examples": [ + { + "name": "Puma", + "id": 1 + } + ] +} +``` + +```yaml +type: object +properties: + id: + type: integer + format: int64 + name: + type: string +required: +- name +examples: +- name: Puma + id: 1 +``` + +###### Model with Boolean Schemas + +```json +{ + "type": "object", + "required": [ + "anySchema" + ], + "properties": { + "anySchema": true, + "cannotBeDefined": false + } +} +``` + +```yaml +type: object +required: +- anySchema +properties: + anySchema: true + cannotBeDefined: false +``` + +###### Models with Composition + +```json +{ + "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" + } + } + } + ] + } + } +} +``` + +```yaml +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 + +```json +{ + "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" + ] + } + ] + }, + "StickInsect": { + "description": "A representation of an Australian walking stick. Note that `StickBug` will be used as the discriminator value.", + "allOf": [ + { + "$ref": "#/components/schemas/Pet" + }, + { + "type": "object", + "properties": { + "petType": { + "const": "StickBug" + }, + "color": { + "type": "string" + } + }, + "required": [ + "color" + ] + } + ] + } + } +} +``` + +```yaml +schemas: + Pet: + type: object + discriminator: petType + properties: + name: + type: string + petType: + type: string + required: + - name + - petType + ## applies to instances with `petType: "Cat"` + ## because that is the schema name + Cat: + 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 + ## applies to instances with `petType: "Dog"` + ## because that is the schema name + Dog: + 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 + ## applies to instances with `petType: "StickBug"` + ## because that is the required value of the discriminator field, + ## overriding the schema name + StickInsect: + description: A representation of an Australian walking stick + allOf: + - $ref: '#/components/schemas/Pet' + - type: object + properties: + petType: + const: StickBug + color: + type: string + required: + - color +``` + + + + + +#### Security Scheme Object + +Defines a security scheme that can be used by the operations. Supported schemes are: + +* User/Password. +* API key (either as user or as password). +* X.509 certificate. +* End-to-end encryption (either symmetric or asymmetric). +* HTTP authentication. +* HTTP API key. +* OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749). +* [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). +* SASL (Simple Authentication and Security Layer) as defined in [RFC4422](https://tools.ietf.org/html/rfc4422). + +##### 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"`, `"oauth2"`, `"openIdConnect"`, `"plain"`, `"scramSha256"`, `"scramSha512"`, and `"gssapi"`. +description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) 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](https://tools.ietf.org/html/rfc7235#section-5.1). +bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. +flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. +openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of an absolute URL. +scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Security Scheme Object Example + +###### User/Password Authentication Sample + +```json +{ + "type": "userPassword" +} +``` + +```yaml +type: userPassword +``` + +###### API Key Authentication Sample + +```json +{ + "type": "apiKey", + "in": "user" +} +``` + +```yaml +type: apiKey +in: user +``` + +###### X.509 Authentication Sample + +```json +{ + "type": "X509" +} +``` + +```yaml +type: X509 +``` + +###### End-to-end Encryption Authentication Sample + +```json +{ + "type": "symmetricEncryption" +} +``` + +```yaml +type: symmetricEncryption +``` + +###### Basic Authentication Sample + +```json +{ + "type": "http", + "scheme": "basic" +} +``` + +```yaml +type: http +scheme: basic +``` + +###### API Key Sample + +```json +{ + "type": "httpApiKey", + "name": "api_key", + "in": "header" +} +``` + +```yaml +type: httpApiKey +name: api_key +in: header +``` + +###### JWT Bearer Sample + +```json +{ + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT" +} +``` + +```yaml +type: http +scheme: bearer +bearerFormat: JWT +``` + +###### Implicit OAuth2 Sample + +```json +{ + "type": "oauth2", + "flows": { + "implicit": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } + }, + "scopes": [ + "write:pets" + ] +} +``` + +```yaml +type: oauth2 +flows: + implicit: + authorizationUrl: https://example.com/api/oauth/dialog + availableScopes: + write:pets: modify pets in your account + read:pets: read your pets +scopes: + - 'write:pets' +``` + +###### SASL Sample + +```json +{ + "type": "scramSha512" +} +``` + +```yaml +type: scramSha512 +``` + +#### OAuth Flows Object + +Allows configuration of the supported OAuth Flows. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|--- +implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow. +password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Protected Credentials flow. +clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. +authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +#### 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 an absolute URL. +tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. +refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. +availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### OAuth Flow Object Examples + +```JSON +{ + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "availableScopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } +} +``` + +```YAML +authorizationUrl: https://example.com/api/oauth/dialog +tokenUrl: https://example.com/api/oauth/token +availableScopes: + write:pets: modify pets in your account + read:pets: read your pets +``` + + + +### 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](#runtimeExpression) is used. + +##### Fixed Fields + +Field Name | Type | Description +---|:---|--- +description | `string` | An optional description of the identifier. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. +location | `string` | **REQUIRED.** A [runtime expression](#runtimeExpression) that specifies the location of the correlation ID. + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Examples + +```json +{ + "description": "Default Correlation ID", + "location": "$message.header#/correlationId" +} +``` + +```yaml +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](#correlationIdObject) and [Operation Reply Address Object](#operationReplyAddressObject). + +The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) 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. + +### Traits Merge Mechanism + +Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the target object. + +#### Example + +An object like the following: + +```yaml +description: A longer description. +traits: + - name: UserSignup + description: Description from trait. + - tags: + - name: user +``` + +Would look like the following after applying traits: + +```yaml +name: UserSignup +description: A longer description. +tags: + - name: user +``` + +### 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\.\x2d_]+$` | 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`](#dataTypeFormat) | 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](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6) +dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.6) +password | `string` | `password` | Used to hint UIs the input needs to be obscured. From 46c41bcfa78b6fee945f3e0c78bbdcfcab800513 Mon Sep 17 00:00:00 2001 From: "allcontributors[bot]" <46447321+allcontributors[bot]@users.noreply.github.com> Date: Mon, 19 Feb 2024 13:02:03 +0100 Subject: [PATCH 11/15] docs: add Pakisan as a contributor for doc, bug, and 2 more (#1036) (cherry picked from commit 60eb71a5c3e8b49522b8c1cae32441289b69d06d) --- .all-contributorsrc | 12 ++++++++++++ README.md | 1 + 2 files changed, 13 insertions(+) diff --git a/.all-contributorsrc b/.all-contributorsrc index 48635c739..84ece03b4 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -483,6 +483,18 @@ "contributions": [ "doc" ] + }, + { + "login": "Pakisan", + "name": "Pavel Bodiachevskii", + "avatar_url": "https://avatars.githubusercontent.com/u/3388414?v=4", + "profile": "https://www.linkedin.com/in/pavel-bo/", + "contributions": [ + "doc", + "bug", + "ideas", + "question" + ] } ], "commitConvention": "none", diff --git a/README.md b/README.md index 30160a14a..f965564c2 100644 --- a/README.md +++ b/README.md @@ -207,6 +207,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
Ace
📋 🤔 🚧 📢
Animesh Kumar
🖋 📖 🚧
Fabrizio Lazzaretti
📖
Pavel Bodiachevskii
📖 🐛 🤔 💬
Check out the [supported schema formats table](#user-content-multiFormatSchemaFormatTable) for more information. Custom values are allowed but their implementation is OPTIONAL. A custom value MUST NOT refer to one of the schema formats listed in the [table](#user-content-multiFormatSchemaFormatTable).
When using [Reference Objects](#reference-object) within the schema, the `schemaFormat` of the referenced resource MUST match the `schemaFormat` of the schema containing the reference. -schema | `any` | **Required**. Definition of the message payload. It can be of any type but defaults to [Schema Object](#user-content-schemaObject). It MUST match the schema format defined in [`schemaFormat`](#user-content-multiFormatSchemaObjectSchemaFormat), including the encoding type. E.g., Avro should be inlined as either a YAML or JSON object instead of as a string to be parsed as YAML or JSON. Non-JSON-based schemas (e.g., Protobuf or XSD) MUST be inlined as a string. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Schema formats table - -The following table contains a set of values that every implementation MUST support. - -Name | Allowed values | Notes ----|:---:|--- -[AsyncAPI 3.0.0 Schema Object](#schema-object) | `application/vnd.aai.asyncapi;version=3.0.0`, `application/vnd.aai.asyncapi+json;version=3.0.0`, `application/vnd.aai.asyncapi+yaml;version=3.0.0` | This is the default when a `schemaFormat` is not provided. -[JSON Schema Draft 07](https://json-schema.org/specification-links.html#user-content-draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | - -The following table contains a set of values that every implementation is RECOMMENDED to support. - -Name | Allowed values | Notes ----|:---:|--- -[Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#user-content-schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` | -[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#user-content-schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | -[RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` | -[Protocol Buffers](https://protobuf.dev/) | `application/vnd.google.protobuf;version=2`, `application/vnd.google.protobuf;version=3` | - - -#### Schema Object - -The Schema Object allows the definition of input and output data types. -These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/). The empty schema (which allows any instance to validate) MAY be represented by the `boolean` value `true` and a schema which allows no instance to validate MAY be represented by the `boolean` value `false`. - -Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-handrews-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01). -Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. For other formats (e.g., Avro, RAML, etc) see [Multi Format Schema Object](#multiFormatSchemaObject). - -##### Properties - -The AsyncAPI Schema Object is a JSON Schema vocabulary which extends JSON Schema Core and Validation vocabularies. As such, any keyword available for those vocabularies is by definition available in AsyncAPI, and will work the exact same way, including but not limited to: - -- title -- type -- required -- multipleOf -- maximum -- exclusiveMaximum -- minimum -- exclusiveMinimum -- maxLength -- minLength -- pattern (This string SHOULD be a valid regular expression, according to the [ECMA 262 regular expression](https://www.ecma-international.org/ecma-262/5.1/#user-content-sec-7.8.5) dialect) -- maxItems -- minItems -- uniqueItems -- maxProperties -- minProperties -- enum -- const -- examples -- if / then / else -- readOnly -- writeOnly -- properties -- patternProperties -- additionalProperties -- additionalItems -- items -- propertyNames -- contains -- allOf -- oneOf -- anyOf -- not - -The following properties are taken from the JSON Schema definition but their definitions were adjusted to the AsyncAPI Specification. - -- description - [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -- format - See [Data Type Formats](#data-type-formats) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats. -- default - Use it to specify that property has a predefined value if no other value is present. 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](#reference-object) can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the `$ref` keyword MUST follow the behavior described by [Reference Object](#reference-object) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#user-content-ref). - -In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#composition-and-inheritance-(polymorphism)) for more details. -externalDocs | [External Documentation Object](#user-content-externalDocumentationObject) \| [Reference Object](#reference-object) | Additional external documentation for this schema. - deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. - -This object MAY be extended with [Specification Extensions](#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 two ways to define the value of a discriminator for an inheriting instance. - -- Use the schema's name. -- Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. - -As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. - -##### Schema Object Examples - -###### Primitive Sample - -```json -{ - "type": "string", - "format": "email" -} -``` - -```yaml -type: string -format: email -``` - -###### Simple Model - -```json -{ - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "address": { - "$ref": "#/components/schemas/Address" - }, - "age": { - "type": "integer", - "format": "int32", - "minimum": 0 - } - } -} -``` - -```yaml -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: - -```json -{ - "type": "object", - "additionalProperties": { - "type": "string" - } -} -``` - -```yaml -type: object -additionalProperties: - type: string -``` - -For a string to model mapping: - -```json -{ - "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/ComplexModel" - } -} -``` - -```yaml -type: object -additionalProperties: - $ref: '#/components/schemas/ComplexModel' -``` - -###### Model with Example - -```json -{ - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "name": { - "type": "string" - } - }, - "required": [ - "name" - ], - "examples": [ - { - "name": "Puma", - "id": 1 - } - ] -} -``` - -```yaml -type: object -properties: - id: - type: integer - format: int64 - name: - type: string -required: -- name -examples: -- name: Puma - id: 1 -``` - -###### Model with Boolean Schemas - -```json -{ - "type": "object", - "required": [ - "anySchema" - ], - "properties": { - "anySchema": true, - "cannotBeDefined": false - } -} -``` - -```yaml -type: object -required: -- anySchema -properties: - anySchema: true - cannotBeDefined: false -``` - -###### Models with Composition - -```json -{ - "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" - } - } - } - ] - } - } -} -``` - -```yaml -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 - -```json -{ - "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" - ] - } - ] - }, - "StickInsect": { - "description": "A representation of an Australian walking stick. Note that `StickBug` will be used as the discriminator value.", - "allOf": [ - { - "$ref": "#/components/schemas/Pet" - }, - { - "type": "object", - "properties": { - "petType": { - "const": "StickBug" - }, - "color": { - "type": "string" - } - }, - "required": [ - "color" - ] - } - ] - } - } -} -``` - -```yaml -schemas: - Pet: - type: object - discriminator: petType - properties: - name: - type: string - petType: - type: string - required: - - name - - petType - ## applies to instances with `petType: "Cat"` - ## because that is the schema name - Cat: - 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 - ## applies to instances with `petType: "Dog"` - ## because that is the schema name - Dog: - 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 - ## applies to instances with `petType: "StickBug"` - ## because that is the required value of the discriminator field, - ## overriding the schema name - StickInsect: - description: A representation of an Australian walking stick - allOf: - - $ref: '#/components/schemas/Pet' - - type: object - properties: - petType: - const: StickBug - color: - type: string - required: - - color -``` - - - - - -#### Security Scheme Object - -Defines a security scheme that can be used by the operations. Supported schemes are: - -* User/Password. -* API key (either as user or as password). -* X.509 certificate. -* End-to-end encryption (either symmetric or asymmetric). -* HTTP authentication. -* HTTP API key. -* OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749). -* [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). -* SASL (Simple Authentication and Security Layer) as defined in [RFC4422](https://tools.ietf.org/html/rfc4422). - -##### 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"`, `"oauth2"`, `"openIdConnect"`, `"plain"`, `"scramSha256"`, `"scramSha512"`, and `"gssapi"`. -description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) 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](https://tools.ietf.org/html/rfc7235#user-content-section-5.1). -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](#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 an absolute URL. -scopes | [`string`] | `oauth2` \| `openIdConnect` | List of the needed scope names. An empty array means no scopes are needed. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Security Scheme Object Example - -###### User/Password Authentication Sample - -```json -{ - "type": "userPassword" -} -``` - -```yaml -type: userPassword -``` - -###### API Key Authentication Sample - -```json -{ - "type": "apiKey", - "in": "user" -} -``` - -```yaml -type: apiKey -in: user -``` - -###### X.509 Authentication Sample - -```json -{ - "type": "X509" -} -``` - -```yaml -type: X509 -``` - -###### End-to-end Encryption Authentication Sample - -```json -{ - "type": "symmetricEncryption" -} -``` - -```yaml -type: symmetricEncryption -``` - -###### Basic Authentication Sample - -```json -{ - "type": "http", - "scheme": "basic" -} -``` - -```yaml -type: http -scheme: basic -``` - -###### API Key Sample - -```json -{ - "type": "httpApiKey", - "name": "api_key", - "in": "header" -} -``` - -```yaml -type: httpApiKey -name: api_key -in: header -``` - -###### JWT Bearer Sample - -```json -{ - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT" -} -``` - -```yaml -type: http -scheme: bearer -bearerFormat: JWT -``` - -###### Implicit OAuth2 Sample - -```json -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "availableScopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - }, - "scopes": [ - "write:pets" - ] -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - availableScopes: - write:pets: modify pets in your account - read:pets: read your pets -scopes: - - 'write:pets' -``` - -###### SASL Sample - -```json -{ - "type": "scramSha512" -} -``` - -```yaml -type: scramSha512 -``` - -#### OAuth Flows Object - -Allows configuration of the supported OAuth Flows. - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -implicit| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Implicit flow. -password| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Resource Owner Protected Credentials flow. -clientCredentials| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Client Credentials flow. -authorizationCode| [OAuth Flow Object](#oauth-flow-object) | Configuration for the OAuth Authorization Code flow. - -This object MAY be extended with [Specification Extensions](#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 an absolute URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. -availableScopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### OAuth Flow Object Examples - -```JSON -{ - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "availableScopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } -} -``` - -```YAML -authorizationUrl: https://example.com/api/oauth/dialog -tokenUrl: https://example.com/api/oauth/token -availableScopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - - - -### 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](#runtime-expression) is used. - -##### Fixed Fields - -Field Name | Type | Description ----|:---|--- -description | `string` | An optional description of the identifier. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -location | `string` | **REQUIRED.** A [runtime expression](#runtime-expression) that specifies the location of the correlation ID. - -This object MAY be extended with [Specification Extensions](#specification-extensions). - -##### Examples - -```json -{ - "description": "Default Correlation ID", - "location": "$message.header#/correlationId" -} -``` - -```yaml -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](#user-content-correlationIdObject) and [Operation Reply Address Object](#operation-reply-address-object). - -The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) 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. - -### Traits Merge Mechanism - -Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the target object. - -#### Example - -An object like the following: - -```yaml -description: A longer description. -traits: - - name: UserSignup - description: Description from trait. - - tags: - - name: user -``` - -Would look like the following after applying traits: - -```yaml -name: UserSignup -description: A longer description. -tags: - - name: user -``` - -### 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`](#data-type-formats) | 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](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) -dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#user-content-section-5.6) -password | `string` | `password` | Used to hint UIs the input needs to be obscured. From c2a8f609733d841526e5734c10db75c6687aa969 Mon Sep 17 00:00:00 2001 From: artellador <34487006+artellador@users.noreply.github.com> Date: Sat, 24 Feb 2024 18:31:28 +0100 Subject: [PATCH 15/15] Removed unnecesary HTML anchors --- spec/asyncapi.md | 120 +++++++++++++++++++++++------------------------ 1 file changed, 60 insertions(+), 60 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 4611f3b99..b8532abbc 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -116,43 +116,43 @@ Aside from the issues mentioned above, there may also be infrastructure configur -## Definitions +## Definitions -### Server +### Server A server MAY be a message broker that is capable of sending and/or receiving between a [sender](#definitionsSender) and [receiver](#definitionsReceiver). A server MAY be a service with WebSocket API that enables message-driven communication between browser-to-server or server-to-server. -### Application +### Application An application is any kind of computer program or a group of them. It MUST be a [sender](#definitionsSender), a [receiver](#definitionsReceiver), or both. An application MAY be a microservice, IoT device (sensor), mainframe process, message broker, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the [server](#definitionsServer) in order to connect and exchange [messages](#definitionsMessage). -### Sender +### Sender A sender is a type of application, that is sending [messages](#definitionsMessage) to [channels](#definitionsChannel). A sender MAY send to multiple channels depending on the [server](#definitionsServer), protocol, and use-case pattern. -### Receiver +### Receiver A receiver is a type of application that is receiving [messages](#definitionsMessage) from [channels](#definitionsChannel). A receiver MAY receive from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. A receiver MAY forward a received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and forwards them. -### Message +### Message A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MAY contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. -### Channel +### Channel A channel is an addressable component, made available by the [server](#definitionsServer), for the organization of [messages](#definitionsMessage). [Sender](#definitionsSender) applications send messages to channels and [receiver](#definitionsReceiver) applications receive messages from channels. [Servers](#definitionsServer) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#definitionsServer) implementation, the channel MAY be included in the message via protocol-defined headers. -### Protocol +### Protocol A protocol is the mechanism (wireline protocol or API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket, Google Pub/Sub, Pulsar. -### Bindings +### Bindings A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only. -## Specification +## Specification -### Format +### Format The files describing the message-driven API in accordance with the AsyncAPI Specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to represent a A2S (AsyncAPI Specification) file. @@ -178,7 +178,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA - Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://www.yaml.org/spec/1.2/spec.html#id2803231) - Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset -### File Structure +### File Structure An AsyncAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Objects](#referenceObject) are used. @@ -187,13 +187,13 @@ It is important to note that everything that is defined in an AsyncAPI document By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. -### Absolute URLs +### Absolute URLs Unless specified otherwise, all properties that are absolute URLs are defined by [RFC3986, section 4.3](https://datatracker.ietf.org/doc/html/rfc3986#section-4.3). -### Schema +### Schema -#### AsyncAPI Object +#### AsyncAPI Object This is the root document object for the API specification. It combines resource listing and API declaration together into one document. @@ -213,7 +213,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -#### AsyncAPI Version String +#### 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. @@ -223,7 +223,7 @@ The patch version will not be considered by tooling, making no distinction betwe 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 +#### Identifier This field represents a unique universal identifier of the [application](#definitionsApplication) the AsyncAPI document is defining. It must conform to the URI format, according to [RFC3986](https://tools.ietf.org/html/rfc3986). @@ -251,7 +251,7 @@ id: 'urn:example:com:smartylighting:streetlights:server' id: 'https://github.com/smartylighting/streetlights-server' ``` -#### Info Object +#### Info Object The object provides metadata about the API. The metadata can be used by the clients if needed. @@ -319,7 +319,7 @@ tags: - name: e-commerce ``` -#### Contact Object +#### Contact Object Contact information for the exposed API. @@ -349,7 +349,7 @@ url: https://www.example.com/support email: support@example.com ``` -#### License Object +#### License Object License information for the exposed API. @@ -376,7 +376,7 @@ name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html ``` -#### Servers Object +#### Servers Object The Servers Object is a map of [Server Objects](#serverObject). @@ -456,7 +456,7 @@ production: description: "This environment is the live environment available for final users." ``` -#### Server Object +#### Server Object An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. @@ -515,7 +515,7 @@ protocol: amqp description: Production RabbitMQ broker (uses the `production` vhost). ``` -#### Server Variable Object +#### Server Variable Object An object representing a Server Variable for server URL template substitution. @@ -563,7 +563,7 @@ variables: - staging ``` -#### Default Content Type +#### 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](#messageObjectContentType) property is omitted. @@ -581,7 +581,7 @@ In case a message can't be encoded/decoded using this value, schema parsers MUST defaultContentType: application/json ``` -#### Channels Object +#### Channels Object An object containing all the [Channel Object](#channelObject) definitions the [Application](#definitionsApplication) MUST use during runtime. @@ -614,7 +614,7 @@ userSignedUp: $ref: '#/components/messages/userSignedUp' ``` -#### Channel Object +#### Channel Object Describes a shared communication channel. @@ -706,13 +706,13 @@ externalDocs: url: 'https://example.com' ``` -#### Channel Address Expressions +#### Channel Address Expressions Channel addresses MAY contain expressions that can be used to define dynamic values. Expressions MUST be composed by a name enclosed in curly braces (`{` and `}`). E.g., `{userId}`. -#### Messages Object +#### Messages Object Describes a map of messages included in a channel. @@ -742,7 +742,7 @@ userCompletedOrder: $ref: '#/components/messages/userCompletedOrder' ``` -#### Operations Object +#### Operations Object Holds a dictionary with all the [operations](#operationObject) this application MUST implement. @@ -802,7 +802,7 @@ onUserSignUp: - $ref: '#/components/operationTraits/kafka' ``` -#### Operation Object +#### Operation Object Describes a specific operation. @@ -905,7 +905,7 @@ reply: - $ref: '#/components/messages/userSignedUpReply' ``` -#### Operation Trait Object +#### Operation Trait Object Describes a trait that MAY be applied to an [Operation Object](#operationObject). This object MAY contain any property from the [Operation Object](#operationObject), except the `action`, `channel`, `messages` and `traits` ones. @@ -943,7 +943,7 @@ bindings: ack: false ``` -#### Operation Reply Object +#### Operation Reply Object Describes the reply part that MAY be applied to an Operation Object. If an operation implements the request/reply pattern, the reply object represents the response message. @@ -957,7 +957,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -#### Operation Reply Address Object +#### Operation Reply Address Object An object that specifies where an operation has to send the reply. @@ -986,7 +986,7 @@ description: Consumer Inbox location: $message.header#/replyTo ``` -#### Parameters Object +#### Parameters Object Describes a map of parameters included in a channel address. @@ -1018,7 +1018,7 @@ parameters: description: Id of the user. ``` -#### Parameter Object +#### Parameter Object Describes a parameter included in a channel address. @@ -1056,7 +1056,7 @@ parameters: location: $message.payload#/user/id ``` -#### Server Bindings Object +#### Server Bindings Object Map describing protocol-specific definitions for a server. @@ -1086,7 +1086,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -#### Channel Bindings Object +#### Channel Bindings Object Map describing protocol-specific definitions for a channel. @@ -1116,7 +1116,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -#### Operation Bindings Object +#### Operation Bindings Object Map describing protocol-specific definitions for an operation. @@ -1146,7 +1146,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -#### Message Bindings Object +#### Message Bindings Object Map describing protocol-specific definitions for a message. @@ -1176,7 +1176,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -#### Message Object +#### Message Object Describes a message received on a given channel and operation. @@ -1347,7 +1347,7 @@ payload: $ref: 'path/to/user-create.avsc/#UserCreate' ``` -#### Message Trait Object +#### Message Trait Object Describes a trait that MAY be applied to a [Message Object](#messageObject). This object MAY contain any property from the [Message Object](#messageObject), except `payload` and `traits`. @@ -1383,7 +1383,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens contentType: application/json ``` -#### Message Example Object +#### Message Example Object Message Example Object represents an example of a [Message Object](#messageObject) and MUST contain either **headers** and/or **payload** fields. @@ -1432,11 +1432,11 @@ payload: someSignupKey: someSignupValue ``` -#### Tags Object +#### Tags Object A Tags object is a list of [Tag Objects](#tagObject). An [Tag Object](#tagObject) in a list can be referenced by [Reference Object](#referenceObject). -#### Tag Object +#### Tag Object Allows adding meta data to a single tag. @@ -1464,7 +1464,7 @@ name: user description: User-related messages ``` -#### External Documentation Object +#### External Documentation Object Allows referencing an external resource for extended documentation. @@ -1491,7 +1491,7 @@ description: Find more info here url: https://example.com ``` -#### Reference Object +#### Reference Object A simple object to allow referencing other components in the specification, internally and externally. @@ -1519,7 +1519,7 @@ This object cannot be extended with additional properties and any properties add $ref: '#/components/schemas/Pet' ``` -#### Components Object +#### 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. @@ -1783,7 +1783,7 @@ components: maximum: 100 ``` -#### Multi Format Schema Object +#### Multi Format Schema Object The Multi Format Schema Object represents a schema definition. It differs from the [Schema Object](#schemaObject) in that it supports multiple schema formats or languages (e.g., JSON Schema, Avro, etc.). @@ -1796,7 +1796,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -##### Schema formats table +##### Schema formats table The following table contains a set of values that every implementation MUST support. @@ -1837,7 +1837,7 @@ channels: type: int ``` -#### Schema Object +#### Schema Object The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/). The empty schema (which allows any instance to validate) MAY be represented by the `boolean` value `true` and a schema which allows no instance to validate MAY be represented by the `boolean` value `false`. @@ -1903,7 +1903,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -###### Composition and Inheritance (Polymorphism) +###### 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. @@ -2302,7 +2302,7 @@ schemas: - color ``` -#### Security Scheme Object +#### Security Scheme Object Defines a security scheme that can be used by the operations. Supported schemes are: @@ -2474,7 +2474,7 @@ scopes: type: scramSha512 ``` -#### OAuth Flows Object +#### OAuth Flows Object Allows configuration of the supported OAuth Flows. @@ -2489,7 +2489,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -#### OAuth Flow Object +#### OAuth Flow Object Configuration details for a supported OAuth Flow @@ -2525,7 +2525,7 @@ availableScopes: read:pets: read your pets ``` -### Correlation ID Object +### Correlation ID Object An object that specifies an identifier at design time that can used for message tracing and correlation. @@ -2554,7 +2554,7 @@ description: Default Correlation ID location: $message.header#/correlationId ``` -### Runtime Expression +### 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](#correlationIdObject) and [Operation Reply Address Object](#operationReplyAddressObject). @@ -2571,7 +2571,7 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org The table below provides examples of runtime expressions and examples of their use in a value: -#### Examples +#### Examples Source Location | Example expression | Notes ---|:---|:---| @@ -2580,7 +2580,7 @@ Message Payload Property | `$message.payload#/messageId` | Correlation ID is set Runtime expressions preserve the type of the referenced value. -### Traits Merge Mechanism +### Traits Merge Mechanism Traits MUST be merged with the target object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined. A property on a trait MUST NOT override the same property on the target object. @@ -2606,7 +2606,7 @@ tags: - name: user ``` -### Specification Extensions +### Specification Extensions While the AsyncAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. @@ -2618,7 +2618,7 @@ Field Pattern | Type | Description 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 +### 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.