diff --git a/components/Asyncapi3Comparison.js b/components/Asyncapi3Comparison.js new file mode 100644 index 000000000000..c4e8800204bf --- /dev/null +++ b/components/Asyncapi3Comparison.js @@ -0,0 +1,562 @@ +import React, { useState } from 'react'; + +/** + * Main comparison that shows the full picture between v2 and v3 + */ +export function Asyncapi3Comparison({ className = '' }) { + const [hoverState, setHoverState] = useState({ + Info: false, + Servers: false, + Paths: false, + PathItem: true, + Summary: false, + Operation: false, + Message: false, + Tags: false, + External: false, + Components: false, + Id: false, + Path: false, + Host: false + }); + + return ( +
+
+

AsyncAPI 2.x

+ +
+
setHoverState(prevState => ({ ...prevState, Info: true }))} onMouseLeave={() => setHoverState({ Info: false })}> + Info +
+
+
setHoverState(prevState => ({ ...prevState, Tags: true }))} onMouseLeave={() => setHoverState({ Tags: false })}> +

Tags

+
+
setHoverState(prevState => ({ ...prevState, External: true }))} onMouseLeave={() => setHoverState({ External: false })}> +

External Docs

+
+
+
+ Servers +
+
+ Server +
+
setHoverState(prevState => ({ ...prevState, Host: true, Path: true }))} onMouseLeave={() => setHoverState({ Host: false, Path: false })}> +

Url

+
+
+
+
+
+
setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ Paths: false })}> + Channels + +
+
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> + Channel Item + +
+
setHoverState(prevState => ({ ...prevState, Operation: true }))} onMouseLeave={() => setHoverState({ Operation: false })}> + Operation (Publish and Subscribe) + +
+
+
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ Message: false })}> + Messages +
+ Message + +
+ Headers +
+
+ Payload +
+
+
+
+
+
+
+
+
+
+
+
+
+

AsyncAPI 3.0

+ +
+
setHoverState(prevState => ({ ...prevState, Info: true }))} onMouseLeave={() => setHoverState({ Info: false })}> + Info +
+
setHoverState(prevState => ({ ...prevState, Tags: true }))} onMouseLeave={() => setHoverState({ Tags: false })}> +

Tags

+
+
setHoverState(prevState => ({ ...prevState, External: true }))} onMouseLeave={() => setHoverState({ External: false })}> +

External Docs

+
+
+
+
+ Servers +
+
+ Server +
+
setHoverState(prevState => ({ ...prevState, Host: true }))} onMouseLeave={() => setHoverState({ Host: false })}> +

Host

+
+
setHoverState(prevState => ({ ...prevState, Path: true }))} onMouseLeave={() => setHoverState({ Path: false })}> +

Pathname

+
+
+
+
+
+
setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ Paths: false })}> + Channels + +
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> + Channel Item +
+
+ address +
+
+
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ Message: false })}> + Messages +
+ Message + +
+ Headers +
+
+ Payload +
+
+
+
+
+
+
+
setHoverState(prevState => ({ ...prevState, Operation: true }))} onMouseLeave={() => setHoverState({ Operation: false })}> + Operations +
+
+ Operation + +
+
+ action (send or receive) +
+
+ channel +
+
+ messages +
+
+
+
+
+
+
+
+ ) +} + +/** + * Used to compare how channels, operations and messages have changed + */ +export function Asyncapi3ChannelComparison({ className = '' }) { + const [hoverState, setHoverState] = useState({ + Paths: false, + PathItem: false, + Operation: false, + Message: false, + }); + + return ( +
+
+

AsyncAPI 2.x

+ +
+
setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ Paths: false })}> + Channels + +
+
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> + Channel Item + +
+
setHoverState(prevState => ({ ...prevState, Operation: true }))} onMouseLeave={() => setHoverState({ Operation: false })}> + Operation (Publish and Subscribe) + +
+
+
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ Message: false })}> + Messages +
+ Message + +
+ Headers +
+
+ Payload +
+
+
+
+
+
+
+
+
+
+
+
+
+

AsyncAPI 3.0

+ +
+
setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ Paths: false })}> + Channels + +
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> + Channel Item +
+
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ Message: false })}> + Messages +
+ Message + +
+ Headers +
+
+ Payload +
+
+
+
+
+
+
setHoverState(prevState => ({ ...prevState, Operation: true }))} onMouseLeave={() => setHoverState({ Operation: false })}> + Operations +
+
+ Operation +
+
+ action (send or receive) +
+
+ channel +
+
+ messages +
+
+
+
+
+
+
+
+ ) +} + +/** + * Shows the comparison between v2 and v3 for the channel IDs and channel address + */ +export function Asyncapi3IdAndAddressComparison({ className = '' }) { + const [hoverState, setHoverState] = useState({ + Paths: false, + PathItem: false, + }); + + return ( +
+
+

AsyncAPI 2.x

+ +
+
setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ Paths: false })}> + Channels +
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> + Channel Item +
+
+
+
+
+

AsyncAPI 3.0

+ +
+
setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ Paths: false })}> + Channels + +
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> + Channel Item + +
+
+ address +
+
+
+
+
+
+
+ ) +} + +/** + * Compares how the server object changes from v2 to v3. + */ +export function Asyncapi3ServerComparison({ className = '' }) { + const [hoverState, setHoverState] = useState({ + Host: false, + path: false, + Servers: false, + }); + + return ( +
+
+

AsyncAPI 2.x

+ +
+
+ Servers +
+
+ Server +
+
setHoverState(prevState => ({ ...prevState, Host: true, Path: true }))} onMouseLeave={() => setHoverState({ Host: false, Path: false })}> +

Url

+
+
+
+
+
+
+
+
+

AsyncAPI 3.0

+ +
+
+ Servers +
+
+ Server +
+
setHoverState(prevState => ({ ...prevState, Host: true }))} onMouseLeave={() => setHoverState({ Host: false })}> +

Host

+
+
setHoverState(prevState => ({ ...prevState, Path: true }))} onMouseLeave={() => setHoverState({ Path: false })}> +

Pathname

+
+
+
+
+
+
+
+
+ ) +} + +/** + * Compare how the meta data moved place between v2 and v3 + */ +export function Asyncapi3MetaComparison({ className = '' }) { + const [hoverState, setHoverState] = useState({ + Info: false, + Tags: false, + External: false + }); + + return ( +
+
+

AsyncAPI 2.x

+ +
+
setHoverState(prevState => ({ ...prevState, Info: true }))} onMouseLeave={() => setHoverState({ Info: false })}> + Info +
+
+
setHoverState(prevState => ({ ...prevState, Tags: true }))} onMouseLeave={() => setHoverState({ Tags: false })}> +

Tags

+
+
setHoverState(prevState => ({ ...prevState, External: true }))} onMouseLeave={() => setHoverState({ External: false })}> +

External Docs

+
+
+
+
+
+

AsyncAPI 3.0

+ +
+
setHoverState(prevState => ({ ...prevState, Info: true }))} onMouseLeave={() => setHoverState({ Info: false })}> + Info +
+
setHoverState(prevState => ({ ...prevState, Tags: true }))} onMouseLeave={() => setHoverState({ Tags: false })}> +

Tags

+
+
setHoverState(prevState => ({ ...prevState, External: true }))} onMouseLeave={() => setHoverState({ External: false })}> +

External Docs

+
+
+
+
+
+
+ ) +} + +/** + * Compares how operations changed from v2 to v3 + */ +export function Asyncapi3OperationComparison({ className = '' }) { + return ( +
+
+

AsyncAPI 2.x

+ +
+
+ Channels + +
+
+ Channel Item + +
+
+ Operation (Publish and Subscribe) +
+
+
+
+
+
+
+
+

AsyncAPI 3.0

+ +
+
+ Operations +
+
+ Operation + +
+
+ action (send or receive) +
+
+
+
+
+
+
+
+ ) +} + +/** + * Compares how the schema and schemaFormat changed location from v2 to v3 + */ +export function Asyncapi3SchemaFormatComparison({ className = '' }) { + const [hoverState, setHoverState] = useState({ + SchemaFormat: false, + Payload: false + }); + + return ( +
+
+

AsyncAPI 2.x

+ +
+
+ components | channels + +
+
+ messages + +
+
+ message +
+
setHoverState(prevState => ({ ...prevState, SchemaFormat: true }))} onMouseLeave={() => setHoverState({ SchemaFormat: false })}> + schemaFormat +
+ +
setHoverState(prevState => ({ ...prevState, Payload: true }))} onMouseLeave={() => setHoverState({ Payload: false })}> + payload +
+
+ schema +
+
+
+
+
+
+
+
+
+
+
+
+

AsyncAPI 3.0

+ +
+
+ components | channels + +
+
+ messages + +
+
+ message +
+
setHoverState(prevState => ({ ...prevState, Payload: true }))} onMouseLeave={() => setHoverState({ Payload: false })}> + payload + +
+
setHoverState(prevState => ({ ...prevState, SchemaFormat: true }))} onMouseLeave={() => setHoverState({ SchemaFormat: false })}> + schemaFormat +
+
+ schema +
+
+
+
+
+
+
+
+
+
+
+
+ ) +} diff --git a/components/DemoAnimation.js b/components/DemoAnimation.js index 107e483c6b56..6e302c74d358 100644 --- a/components/DemoAnimation.js +++ b/components/DemoAnimation.js @@ -44,7 +44,7 @@ export default function DemoAnimation({ className = '' }) { const common = ( <>
- asyncapi: 2.6.0 + asyncapi: 3.0.0
info: @@ -85,10 +85,34 @@ export default function DemoAnimation({ className = '' }) { channels:
-   user/signedup: +   userSignedup:
-     subscribe: +     address:'user/signedup' +
+
+     messages: +
+
+       userSignedupMessage: +
+
+         $ref:'#/components/messages/UserSignedUp' +
+
+ operations: +
+
+   processUserSignups: +
+
+     action:'receive' +
+
+     channel: +
+
+       $ref: '#/channels/userSignedup'
, @@ -99,12 +123,6 @@ export default function DemoAnimation({ className = '' }) { function renderUntilMessagePayload(callback) { return renderTyping( <> -
-       message: -
-
-         $ref: '#/components/messages/UserSignedUp' -
components:
@@ -242,7 +260,7 @@ export default function DemoAnimation({ className = '' }) {
- SUB user/signedup + RECEIVES user/signedup
diff --git a/components/data/buckets.js b/components/data/buckets.js index a171d2718858..8ecab700fa10 100644 --- a/components/data/buckets.js +++ b/components/data/buckets.js @@ -4,6 +4,7 @@ import IconUseCases from '../icons/UseCases' import IconGuide from '../icons/Guide' import IconSpec from '../icons/Spec' import IconUsers from '../icons/Users' +import IconMigration from '../icons/Migration' export const buckets = [ { @@ -51,7 +52,16 @@ export const buckets = [ borderClassName: 'border-yellow-200', Icon: IconSpec, }, - { + { + name: 'migration', + title: 'Migration', + description: 'Our migration guides on how to upgrade to newer AsyncAPI versions.', + link: '/docs/migration', + className: 'bg-blue-400', + borderClassName: 'border-blue-400', + Icon: IconMigration, + }, + { name: 'community', title: 'Community', description: 'Our Community section documents the community guidelines and resources.', @@ -61,7 +71,7 @@ export const buckets = [ Icon: IconUsers, }, ].map(bucket => { - // we need such a mapping for some parts of website, e.g navigation blocks use the `icon` property, not `Icon` etc. + // we need such a mapping for some parts of website, e.g navigation blocks use the `icon` property, not `Icon` etc. return { ...bucket, href: bucket.link, diff --git a/components/icons/Migration.js b/components/icons/Migration.js new file mode 100644 index 000000000000..77180efeba87 --- /dev/null +++ b/components/icons/Migration.js @@ -0,0 +1,15 @@ +export default function IconUsers({ ...rest }) { + // + return ( + + + + ); +} diff --git a/components/icons/Users.js b/components/icons/Users.js index c46a89deb774..9f43fdcb633d 100644 --- a/components/icons/Users.js +++ b/components/icons/Users.js @@ -1,14 +1,14 @@ export default function IconUsers({ ...rest }) { return ( - diff --git a/components/navigation/learningItems.js b/components/navigation/learningItems.js index 65ba491f9a96..f04382b44aea 100644 --- a/components/navigation/learningItems.js +++ b/components/navigation/learningItems.js @@ -4,6 +4,7 @@ import IconPlant from '../icons/Plant' import IconGuide from '../icons/Guide' import IconPaper from '../icons/Paper' import IconUsers from '../icons/Users' +import IconMigration from '../icons/Migration' export default [ { href: '/docs/concepts', icon: IconRocket, className: 'bg-secondary-200', title: 'Concepts', description: 'Our Concepts section defines the concepts of AsyncAPI features and capabilities.' }, @@ -11,5 +12,6 @@ export default [ { href: '/docs/tools', icon: IconPlant, className: 'bg-green-200', title: 'Tools', description: 'Our Tools section documents the AsyncAPI tools ecosystem.' }, { href: '/docs/guides', icon: IconGuide, className: 'bg-primary-200', title: 'Guides', description: `Our Guides section teaches AsyncAPI's capabilities at a high level.` }, { href: '/docs/reference', icon: IconPaper, className: 'bg-yellow-200', title: 'Reference', description: `Our Reference section documents the AsyncAPI specification.` }, + { href: '/docs/migration', icon: IconMigration, className: 'bg-blue-400', title: 'Migrations', description: `Our migration guides on how to upgrade to newer AsyncAPI versions.` }, { href: '/docs/community', icon: IconUsers, className: 'bg-red-200', title: 'Community', description: `Our Community section documents the community guidelines and resources.` }, ] diff --git a/cypress/test/Asyncapi3Comparison.cy.js b/cypress/test/Asyncapi3Comparison.cy.js new file mode 100644 index 000000000000..15893bfd5f9d --- /dev/null +++ b/cypress/test/Asyncapi3Comparison.cy.js @@ -0,0 +1,40 @@ +import { mount } from '@cypress/react' +import {Asyncapi3Comparison, Asyncapi3ChannelComparison, Asyncapi3IdAndAddressComparison, Asyncapi3MetaComparison, Asyncapi3OperationComparison, Asyncapi3SchemaFormatComparison, Asyncapi3ServerComparison} from '../../components/Asyncapi3Comparison' + +describe('Asyncapi3Comparison.cy', () => { + describe('Asyncapi3Comparison', () => { + it('renders without errors', () => { + mount(); + }); + }); + describe('Asyncapi3ChannelComparison', () => { + it('renders without errors', () => { + mount(); + }); + }); + describe('Asyncapi3IdAndAddressComparison', () => { + it('renders without errors', () => { + mount(); + }); + }); + describe('Asyncapi3MetaComparison', () => { + it('renders without errors', () => { + mount(); + }); + }); + describe('Asyncapi3OperationComparison', () => { + it('renders without errors', () => { + mount(); + }); + }); + describe('Asyncapi3SchemaFormatComparison', () => { + it('renders without errors', () => { + mount(); + }); + }); + describe('Asyncapi3ServerComparison', () => { + it('renders without errors', () => { + mount(); + }); + }); +}); diff --git a/pages/blog/release-notes-3.0.0.md b/pages/blog/release-notes-3.0.0.md index 60b891da03c9..0c7380a3f13a 100644 --- a/pages/blog/release-notes-3.0.0.md +++ b/pages/blog/release-notes-3.0.0.md @@ -5,7 +5,7 @@ type: Communication tags: - Specification - Release Notes -cover: /img/posts/release-notes-2.4.0/cover.webp +cover: /img/posts/release-notes-3.0.0/cover.webp authors: - name: Jonas Lagoni photo: /img/avatars/jonaslagoni.webp @@ -70,6 +70,8 @@ channels: ... ``` +Related to: [#94](https://github.com/asyncapi/spec/issues/94) | Pull request: [#827](https://github.com/asyncapi/spec/pull/827) + ### Publish and subscribe confusion In v2, the `publish` and `subscribe` operation keywords have always been confusing. Does it mean my application publishes to the channel? Does it mean you publish for me? Who are you in this context? @@ -122,6 +124,7 @@ We have seen many use cases where an AsyncAPI document has been used as a form o ``` asyncapi: 3.0.0 +... components: ... ``` @@ -136,6 +139,7 @@ The server security information is also now an array instead of an object. ``` asyncapi: 3.0.0 +... servers: SomeServer: security: @@ -144,7 +148,6 @@ channels: SomeChannel: servers: - $ref: '#/servers/SomeServer' -... components: securitySchemes: SomeSecurity: @@ -162,6 +165,7 @@ There has been some inconsistency between which metadata fields are available in ``` asyncapi: 3.0.0 +... servers: SomeServer: title: Some Server title @@ -188,6 +192,7 @@ Therefore the root `tags` and `externalDocs` have been moved to the info object. ``` asyncapi: 3.0.0 +... info: ... externalDocs: @@ -205,6 +210,7 @@ There has been some confusion about what the `url` of a server should contain; i ``` asyncapi: 3.0.0 +... servers: localhost: host: localhost @@ -225,6 +231,7 @@ This is a bit of a mixture between some of the features, that all added a little ``` asyncapi: 3.0.0 +... components: ... replies: @@ -281,6 +288,7 @@ In v3, schemaFormat has been removed from the message object and message trait o ``` asyncapi: 3.0.0 +... components: schemas: avroSchema: @@ -303,6 +311,7 @@ Parameters can now only have the following properties: `enum`, `default`, `descr ``` asyncapi: 3.0.0 +... channels: userSignup: address: user/{userId}/signedup @@ -313,7 +322,7 @@ channels: Issues: [#583](https://github.com/asyncapi/spec/issues/583) | Pull request: [#935](https://github.com/asyncapi/spec/pull/935) | Specification information: https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#parameterObject -### Editorial changes +### Editorial Changes We have [removed the note that stated we strived to be compatible with OpenAPI where possible]([#933](https://github.com/asyncapi/spec/pull/933)) because, with the recent changes, this is no longer the case. That said, we still strive to make the different specs as interoperable as possible i.e., with Avro, RAML, OpenAPI Schema, etc. @@ -322,4 +331,5 @@ Spec 3.0 have been a massive undertaking, so I would like to say a huge "thank y Thank you, xxxxxxxxxxxxxxxxx -> Photo by Alexandru Tudorache on Unsplash +> Photo by Jonathan Borba on Unsplash + diff --git a/pages/docs/community/_section.md b/pages/docs/community/_section.md index 6874743a00fe..1ef99a267b1b 100644 --- a/pages/docs/community/_section.md +++ b/pages/docs/community/_section.md @@ -1,4 +1,4 @@ --- title: 'Community' -weight: 6 ---- \ No newline at end of file +weight: 7 +--- diff --git a/pages/docs/migration/_section.md b/pages/docs/migration/_section.md new file mode 100644 index 000000000000..48556fd333c5 --- /dev/null +++ b/pages/docs/migration/_section.md @@ -0,0 +1,4 @@ +--- +title: Migrations +weight: 6 +--- diff --git a/pages/docs/migration/index.md b/pages/docs/migration/index.md new file mode 100644 index 000000000000..195bcc35cf54 --- /dev/null +++ b/pages/docs/migration/index.md @@ -0,0 +1,15 @@ +--- +title: "Overview" +--- +Migration to a new major version is always difficult, and AsyncAPI is no exception, but we want to provide as smooth a transition as possible. + +If you are just looking to update your AsyncAPI document, then we suggest you use the [AsyncAPI converter](https://github.com/asyncapi/converter-js). You can do this directly in the CLI with: + +```bash +asyncapi convert asyncapi.json --output=new_asyncapi.json --target-version=x.x.x +``` + +For a detailed read-through about all the changes (non-breaking as well), please do [read the release notes](https://www.asyncapi.com/blog?tags=Release+Notes) for the desired version before hand, as it will give you some more context about the changes. + +Here are all the migration guides: +- [Migrating to v3](/docs/migration/migrating-to-v3) diff --git a/pages/docs/migration/migrating-to-v3.md b/pages/docs/migration/migrating-to-v3.md new file mode 100644 index 000000000000..9d20b8bbefcb --- /dev/null +++ b/pages/docs/migration/migrating-to-v3.md @@ -0,0 +1,395 @@ +--- +title: "Migrating to v3" +--- +Migration to a new major version is always difficult, and AsyncAPI is no exception. To provide as smooth a transition as possible, this document shows the breaking changes between AsyncAPI v2 and v3 in an interactive manner. + +If you want to update your AsyncAPI document, use the [AsyncAPI converter](https://github.com/asyncapi/converter-js) directly in the CLI with the following command: + +```bash +asyncapi convert asyncapi.json --output=asyncapi_v3.json --target-version=3.0.0 +``` + +For a detailed read-through about all the changes (non-breaking as well), read all the [v3 release notes](/blog/release-notes-3.0.0) first to acquire additional context about the changes introduced in v3. + +import {Asyncapi3Comparison, Asyncapi3ChannelComparison, Asyncapi3IdAndAddressComparison, Asyncapi3MetaComparison, Asyncapi3OperationComparison,Asyncapi3SchemaFormatComparison, Asyncapi3ServerComparison} from '../../../components/Asyncapi3Comparison' + + + +## Moved metadata + +In v2, two properties of `tags` and `externalDocs` were placed outside of the [Info Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#infoObject). For consistency, `info` has been moved in v3. + + + +```yml +asyncapi: 2.6.0 +info: + ... +externalDocs: + description: Find more info here + url: https://www.asyncapi.com +tags: + - name: e-commerce +``` + +```yml +asyncapi: 3.0.0 +info: + externalDocs: + description: Find more info here + url: https://www.asyncapi.com + tags: + - name: e-commerce +``` + +## Server URL splitting up +There was occasional confusion regarding what the URL of a [Server Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#serverObject) should include. + + + +In v2, the URL was often a lengthy string, sometimes redundantly including details like the protocol. + +In v3, the `url` property has been divided into `host`, `pathname`, and `protocol`—as was the case in v2—making the information more explicit. + +```yml +asyncapi: 2.6.0 +servers: + production: + url: "amqp://rabbitmq.in.mycompany.com:5672/production" + protocol: "amqp" +``` + +```yml +asyncapi: 3.0.0 +servers: + production: + host: "rabbitmq.in.mycompany.com:5672", + pathname: "/production", + protocol: "amqp", +``` + +## Operation, channel, and message decoupling + +The decoupling of operations, channels, and messages is the most significant breaking change in v3, fundamentally altering how they relate to each other. + + + +In v2, reusing channels and having multiple operations per channel, such as operation variants, was impossible. + +In v3, this has become possible, emphasizing that a channel and message should be independent of the operations performed. + +For message brokers like Kafka, this is akin to defining topics and their associated messages. In REST interfaces, it pertains to the path and request type (e.g., POST, GET), along with the corresponding request and response messages. For WebSocket, it encompasses all messages transmitted through the WebSocket server. For Socket.IO, it delineates all the rooms and their messages. + +Channels are now reusable across multiple AsyncAPI documents, each facilitating a slightly different action. + +```yml +asyncapi: 2.6.0 +... +channels: + user/signedup: + publish: + message: + payload: + type: object + properties: + displayName: + type: string + description: Name of the user +``` + +```yml +asyncapi: 3.0.0 +... +channels: + UserSignup: + address: "user/signedup" + messages: + UserMessage: + payload: + type: object + properties: + displayName: + type: string + description: Name of the user +operations: + ConsumeUserSignups: + action: receive + channel: + $ref: "#/channels/UserSignup" +``` + +Read more about the confusion between publishing and subscribing in the [Operation keywords](#operation-keywords) section. + +## Channel address and channel key + +Another breaking change is that the channel key no longer represents the channel path. Instead, it's now an arbitrary unique ID. The channel paths are now defined using the `address` property within the [Channel Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#channelObject). + + + +In v2, the channel's `address/topic/path` doubled as its ID, hindering reusability and preventing the definition of scenarios where the same address was used in different contexts. + +In v3, the `address/topic/path` has been shifted to an `address` property, allowing the channel ID to be distinct and arbitrary. + +```yml +asyncapi: 2.6.0 +... +channels: + test/path: + ... +``` + +```yml +asyncapi: 3.0.0 +channels: + testPathChannel: + address: "test/path" +``` + +## Operation keywords + +Another significant change is the shift away from defining operations using `publish` and `subscribe`, which had inverse meanings for your application. Now, you directly specify your application's behavior using `send` and `receive` via the `action` property in the [Operation Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationObject). + + + +In v2, the `publish` and `subscribe` operations consistently caused confusion, even among those familiar with the intricacies. + +When you specified `publish`, it implied that others could `publish` to this channel since your application subscribed to it. Conversely, `subscribe` meant that others could subscribe because your application was the one publishing. + +In v3, these operations have been entirely replaced with an `action` property that clearly indicates what your application does. That eliminates ambiguities related to other parties or differing perspectives. + +Read more information about the confusion between publishing and subscribing: +- Fran Méndez's [Proposal to solve publish/subscribe confusion](https://github.com/asyncapi/spec/issues/618) +- Nic Townsend's blog post [Demystifying the Semantics of Publish and Subscribe](https://www.asyncapi.com/blog/publish-subscribe-semantics) + +Here is an example where the application both consumes and produces messages to the test channel: + +```yml +asyncapi: 2.6.0 +... +channels: + test/path: + subscribe: + ... + publish: + ... +``` + +```yml +asyncapi: 3.0.0 +channels: + testPathChannel: + address: "test/path" + ... +operations: + publishToTestPath: + action: send + channel: + $ref: "#/channels/testPathChannel" + consumeFromTestPath: + action: receive + channel: + $ref: "#/channels/testPathChannel" +``` + +## Messages instead of message +In v2, channels were defined with one or more messages using the `oneOf` property. + +In v3, messages are defined using the [Messages Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#messagesObject). For a channel with multiple messages, you specify multiple key-value pairs. For a channel with just one message, you use a single key-value pair. + +```yml +asyncapi: 2.6.0 +... +channels: + user/signedup: + message: + oneOf: + - ... + - ... + +asyncapi: 2.6.0 +... +channels: + user/signedup: + message: + ... +``` + +```yml +asyncapi: 3.0.0 +... +channels: + UserSignup: + address: user/signedup + messages: + UserMessage: + ... + UserMessage2: + ... + +asyncapi: 3.0.0 +... +channels: + UserSignup: + address: user/signedup + messages: + UserMessage: + ... +``` + +## Unifying explicit and implicit references + +In v2, implicit references were allowed in certain instances. For instance, the server security configuration was identified by name, linking to a [Security Schema Object](https://www.asyncapi.com/docs/reference/specification/v2.6.0#securitySchemeObject) within the components. Similarly, a channel could reference global servers by name. + +In v3, all such references MUST be explicit. As a result, we made a minor modification to the [Server Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#serverObject) `security` property, transforming it from an object to an array. The details regarding required scopes for OAuth and OpenID Connect were then relocated to the [Security Scheme Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#securitySchemeObject). + +```yml +asyncapi: 2.6.0 +servers: + production: + ... + security: + oauth_test: ["write:pets"] +... +channels: + test/path: + severs: + - production +components: + securitySchemes: + oauth_test: + 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' +``` + +```yml +asyncapi: 3.0.0 +servers: + production: + ... + security: + - $ref: "#/components/securitySchemes/oauth_test" +... +channels: + test/path: + severs: + - $ref: "#/servers/production" +components: + securitySchemes: + oauth_test: + 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" +``` + +## New trait behavior +In v2, traits invariably overwrote any duplicate properties specified both in the traits and the corresponding object. For instance, if both message traits and the message object defined headers, only the headers from the message traits would be recognized, effectively overriding those in the Message Object. + +In v3, this behavior has been revised. The primary objects now take precedence over any definitions in the traits. Such an adjustment is consistent for traits in both operation and message objects. + +Here is a message object and associated traits: +```yml +messageId: userSignup +description: A longer description. +payload: + $ref: '#/components/schemas/userSignupPayload' +traits: + - summary: Action to sign a user up. + description: Description from trait. +``` + +In v2, after applying the traits, the complete message object appeared as follows. Note how the `description` was overridden: + +```yml +messageId: userSignup +summary: Action to sign a user up. +description: Description from trait. +payload: + $ref: '#/components/schemas/userSignupPayload' +``` +That is the default behavior of the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm we use. + +In v3, we've instituted a guideline stating, `A property on a trait MUST NOT override the same property on the target object`. Consequently, after applying the traits in v3, the complete message object appears as follows: + +```yml +messageId: userSignup +summary: Action to sign a user up. +description: A longer description. # it's still description from "main" object +payload: + $ref: '#/components/schemas/userSignupPayload' +``` +Notice how the `description` is no longer overwritten. + +## Schema format and schemas + +One limitation with schemas has always been the inability to reuse them across different schema formats. + + + +In v2, the details about which schema format the payload uses are found within the message object, rather than being directly linked to the schema itself. Such separation hampers reusability, as the two data points aren't directly correlated. + +To address this in v3, we've introduced [a multi-format schema object](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#multiFormatSchemaObject) that consolidates this information. Consequently, whenever you utilize `schemaFormat`, you'll need to modify the schema as follows: + +```yml +asyncapi: 2.6.0 +... +channels: + user/signedup: + publish: + message: + schemaFormat: 'application/vnd.apache.avro;version=1.9.0' + payload: + type: record + name: User + namespace: com.company + doc: User information + fields: + - name: displayName + type: string +``` + +```yml +asyncapi: 3.0.0 +... +channels: + UserSignup: + address: user/signedup + messages: + userSignup: + payload: + schemaFormat: 'application/vnd.apache.avro;version=1.9.0' + schema: + type: record + name: User + namespace: com.company + doc: User information + fields: + - name: displayName + type: string +``` + +## Optional channels +In v3, defining channels has become entirely optional, eliminating the need to specify channels as an empty object (required in v2). + +```yml +asyncapi: 2.6.0 +... +channels: {} +``` + +```yml +asyncapi: 3.0.0 +... +``` diff --git a/pages/docs/reference/specification/v2.0.0.md b/pages/docs/reference/specification/v2.0.0.md deleted file mode 100644 index 00f27112ab71..000000000000 --- a/pages/docs/reference/specification/v2.0.0.md +++ /dev/null @@ -1,2205 +0,0 @@ -# AsyncAPI Specification - -#### Disclaimer - -Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). Mainly because **it's a great work** and we want to keep as much compatibility as possible with the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification). - -#### Version 2.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](http://www.ietf.org/rfc/rfc2119.txt). - -The AsyncAPI Specification is licensed under [The Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). - -## Introduction - -The AsyncAPI Specification is a project used to describe and document message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, etc). - -The AsyncAPI Specification defines a set of files required to describe such an API. -These files can then be used to create utilities, such as documentation, integration and/or testing tools. - -The file(s) MUST describe the operations an [application](#definitionsApplication) accepts. For instance, consider the following AsyncAPI definition snippet: - -```yaml -user/signedup: - subscribe: - $ref: "#/components/messages/userSignUp" -``` - -It means that the [application](#definitionsApplication) allows [consumers](#definitionsConsumer) to subscribe to the `user/signedup` [channel](#definitionsChannel) to receive userSignUp [messages](#definitionsMessage). - -**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 and/or the topology. - -## Definitions - -#### Application -An application is any kind of computer program or a group of them. It MUST be a [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the server in order to connect and exchange [messages](#definitionsMessage). - -#### Producer -A producer is a type of application, connected to a server, that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the server, protocol, and use-case pattern. - -#### Consumer -A consumer is a type of application, connected to a server via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the server, protocol, and the use-case pattern. - -#### Message -A message is the mechanism by which information is exchanged via a channel between servers and applications. A message MUST contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#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, for the organization of [messages](#definitionsMessage). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume messages from channels. Servers MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the server implementation, the channel MAY be included in the message via protocol-defined headers. - -#### Protocol -A protocol is the mechanism (wireline protocol OR API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocol include, but are not limited to, AMQP, HTTP, JMS, Kafka, MQTT, STOMP, WebSocket. - -## 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](http://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](http://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 - -The A2S representation of the API is made of a single file. -However, parts of the definitions can be split into separate files, at the discretion of the user. -This is applicable for `$ref` fields in the specification as follows from the [JSON Schema](https://json-schema.org/understanding-json-schema/structuring.html) definitions. - -By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. - -### Schema - -#### AsyncAPI Object - -This is the root document object for the API specification. -It combines resource listing and API declaration together into one document. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -asyncapi | [AsyncAPI Version String](#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. -channels | [Channels Object](#channelsObject) | **Required** The available channels and messages for the API. -components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. -tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. - - -This object can 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](http://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:com:smartylighting:streetlights:server" -} -``` - -```yaml -id: 'urn: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](http://spec.commonmark.org/) can be used for rich text representation. -termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. -contact | [Contact Object](#contactObject) | The contact information for the exposed API. -license | [License Object](#licenseObject) | The license information for the exposed API. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Info Object Example: - -```json -{ - "title": "AsyncAPI Sample App", - "description": "This is a sample server.", - "termsOfService": "http://asyncapi.org/terms/", - "contact": { - "name": "API Support", - "url": "http://www.asyncapi.org/support", - "email": "support@asyncapi.org" - }, - "license": { - "name": "Apache 2.0", - "url": "http://www.apache.org/licenses/LICENSE-2.0.html" - }, - "version": "1.0.1" -} -``` - -```yaml -title: AsyncAPI Sample App -description: This is a sample server. -termsOfService: http://asyncapi.org/terms/ -contact: - name: API Support - url: http://www.asyncapi.org/support - email: support@asyncapi.org -license: - name: Apache 2.0 - url: http://www.apache.org/licenses/LICENSE-2.0.html -version: 1.0.1 -``` - -#### Contact Object - -Contact information for the exposed API. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -name | `string` | The identifying name of the contact person/organization. -url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. -email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Contact Object Example: - -```json -{ - "name": "API Support", - "url": "http://www.example.com/support", - "email": "support@example.com" -} -``` - -```yaml -name: API Support -url: http://www.example.com/support -email: support@example.com -``` - -#### License Object - -License information for the exposed API. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -name | `string` | **Required.** The license name used for the API. -url | `string` | A URL to the license used for the API. MUST be in the format of a URL. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### License Object Example: - -```json -{ - "name": "Apache 2.0", - "url": "http://www.apache.org/licenses/LICENSE-2.0.html" -} -``` - -```yaml -name: Apache 2.0 -url: http://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) | The definition of a server this application MAY connect to. - -##### Servers Object Example - -```json -{ - "production": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" - } -} -``` - -```yaml -production: - url: development.gigantic-server.com - description: Development server - protocol: kafka - protocolVersion: '1.0.0' -``` - - -#### Server Object - -An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. -protocol | `string` | **REQUIRED**. The protocol this URL supports for connection. Supported protocol include, but are not limited to: `amqp`, `amqps`, `http`, `https`, `jms`, `kafka`, `kafka-secure`, `mqtt`, `secure-mqtt`, `stomp`, `stomps`, `ws`, `wss`. -protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. -description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. -variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. -bindings | [Server Bindings Object](#serverBindingsObject) | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Server Object Example - -A single server would be described as: - -```json -{ - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" -} -``` - -```yaml -url: development.gigantic-server.com -description: Development server -protocol: kafka -protocolVersion: '1.0.0' -``` - -The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): - -```json -{ - "servers": { - "development": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "staging": { - "url": "staging.gigantic-server.com", - "description": "Staging server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "production": { - "url": "api.gigantic-server.com", - "description": "Production server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - } - } -} -``` - -```yaml -servers: - development: - url: development.gigantic-server.com - description: Development server - protocol: amqp - protocolVersion: 0.9.1 - staging: - url: staging.gigantic-server.com - description: Staging server - protocol: amqp - protocolVersion: 0.9.1 - production: - url: api.gigantic-server.com - description: Production server - protocol: amqp - protocolVersion: 0.9.1 -``` - -The following shows how variables can be used for a server configuration: - -```json -{ - "servers": [ - { - "url": "{username}.gigantic-server.com:{port}/{basePath}", - "description": "The production API server", - "protocol": "secure-mqtt", - "variables": { - "username": { - "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" - }, - "port": { - "enum": [ - "8883", - "8884" - ], - "default": "8883" - }, - "basePath": { - "default": "v2" - } - } - } - ] -} -``` - -```yaml -servers: -- url: '{username}.gigantic-server.com:{port}/{basePath}' - description: The production API server - protocol: secure-mqtt - variables: - username: - # note! no enum here means it is an open value - default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` - port: - enum: - - '8883' - - '8884' - default: '8883' - basePath: - # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` - default: v2 -``` - - -#### Server Variable Object - -An object representing a Server Variable for server URL template substitution. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. -default | `string` | The default value to use for substitution, and to send, if an alternate value is _not_ supplied. -description | `string` | An optional description for the server variable. [CommonMark syntax](http://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). - - - - - -#### 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 - -Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers. - -Channels are also known as "topics", "routing keys", "event types" or "paths". - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{channel} | [Channel Item Object](#channelItemObject) | A relative path to an individual channel. The field name MUST be in the form of a [RFC 6570 URI template](https://tools.ietf.org/html/rfc6570). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channelBindingsObject) to define them. - -##### Channels Object Example - -```json -{ - "user/signedup": { - "subscribe": { - "$ref": "#/components/messages/userSignedUp" - } - } -} -``` - -```yaml -user/signedup: - subscribe: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### Channel Item Object - -Describes the operations available on a single channel. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -$ref | `string` | Allows for an external definition of this channel item. The referenced structure MUST be in the format of a [Channel Item Object](#channelItemObject). If there are conflicts between the referenced definition and this Channel Item's definition, the behavior is *undefined*. -description | `string` | An optional description of this channel item. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation. -publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation. -parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)). -bindings | [Channel Bindings Object](#channelBindingsObject) | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Channel Item Object Example - -```json -{ - "description": "This channel is used to exchange messages about users signing up", - "subscribe": { - "summary": "A user signed up.", - "message": { - "description": "A longer description of the message", - "payload": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/user" - }, - "signup": { - "$ref": "#/components/schemas/signup" - } - } - } - } - }, - "bindings": { - "amqp": { - "is": "queue", - "queue": { - "exclusive": true - } - } - } -} -``` - -```yaml -description: This channel is used to exchange messages about users signing up -subscribe: - summary: A user signed up. - message: - description: A longer description of the message - payload: - type: object - properties: - user: - $ref: "#/components/schemas/user" - signup: -bindings: - amqp: - is: queue - queue: - exclusive: true -``` - -Using `oneOf` to specify multiple messages per operation: - -```json -{ - "subscribe": { - "message": { - "oneOf": [ - { "$ref": "#/components/messages/signup" }, - { "$ref": "#/components/messages/login" } - ] - } - } -} -``` - -```yaml -subscribe: - message: - oneOf: - - $ref: '#/components/messages/signup' - - $ref: '#/components/messages/login' -``` - - - - - - - -#### Operation Object - -Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. For example, an operation might describe a chat application use case where a user sends a text message to a group. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -tags | [[Tag Object](#tagObject)] | A list of tags for API documentation control. Tags can be used for logical grouping of operations. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. -bindings | Map[`string`, [Operation Bindings Object](#operationBindingsObject)] | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. -traits | [[Operation Trait Object](#operationTraitObject)] | A list of traits to apply to the operation object. Traits MUST be merged into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. -message | [Message Object](#messageObject) | A definition of the message that will be published or received on this channel. `oneOf` is allowed here to specify multiple messages, however, **a message MUST be valid only against one of the referenced message objects.** - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Operation Object Example - -```json -{ - "operationId": "registerUser", - "summary": "Action to sign a user up.", - "description": "A longer description", - "tags": [ - { "name": "user" }, - { "name": "signup" }, - { "name": "register" } - ], - "message": { - "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" - } - } - } - }, - "bindings": { - "amqp": { - "ack": false - }, - }, - "traits": [ - { "$ref": "#/components/operationTraits/kafka" } - ] -} -``` - -```yaml -operationId: registerUser -summary: Action to sign a user up. -description: A longer description -tags: - - name: user - - name: signup - - name: register -message: - 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" -bindings: - amqp: - ack: false -traits: - - $ref: "#/components/operationTraits/kafka" -``` - - - - -#### 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 `message` and `traits`. - -If you're looking to apply traits to a message, see the [Message Trait Object](#messageTraitObject). - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. -bindings | [Operation Bindings Object](#operationBindingsObject) | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Operation Trait Object Example - -```json -{ - "bindings": { - "amqp": { - "ack": false - } - } -} -``` - -```yaml -bindings: - amqp: - ack: false -``` - - - - -#### Parameters Object - -Describes a map of parameters included in a channel name. - -This map MUST contain all the parameters used in the parent channel name. - -##### Patterned Fields - -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 name. - -##### Parameters Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - } - } - }, - "subscribe": { - "$ref": "#/components/messages/userSignedUp" - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - subscribe: - $ref: "#/components/messages/userSignedUp" -``` - - - - - -#### Parameter Object - -Describes a parameter included in a channel name. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -description | `string` | A verbose explanation of the parameter. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -schema | [Schema Object](#schemaObject) | Definition of the parameter. -location | `string` | A [runtime expression](#runtimeExpression) that specifies the location of the parameter value. Even when a definition for the target field exists, it MUST NOT be used to validate this parameter but, instead, the `schema` property MUST be used. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Parameter Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - }, - "location": "$message.payload#/user/id" - } - }, - "subscribe": { - "$ref": "#/components/messages/userSignedUp" - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - location: $message.payload#/user/id - subscribe: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### 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. -`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. -`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. - - - - -#### 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. -`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. -`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. - - - - -#### 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. -`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. -`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. - - - - - - -#### 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. -`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. -`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. - - - - - - - - - -#### Message Object - -Describes a message received on a given channel and operation. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -headers | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -payload | `any` | Definition of the message payload. It can be of any type but defaults to [Schema object](#schemaObject). -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). Check out the [supported schema formats table](#messageObjectSchemaFormatTable) 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](#messageObjectSchemaFormatTable). -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](http://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message. -bindings | [Message Bindings Object](#messageBindingsObject) | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. -examples | [Map[`string`, `any`]] | An array with examples of valid message objects. -traits | [[Message Trait Object](#messageTraitObject)] | A list of traits to apply to the message object. Traits MUST be merged into the message object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Message Object](#messageObject). - -This object can 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 2.0.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.0.0`, `application/vnd.aai.asyncapi+json;version=2.0.0`, `application/vnd.aai.asyncapi+yaml;version=2.0.0` | This is the default when a `schemaFormat` is not provided. -[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` | -[JSON Schema Draft 07](http://json-schema.org/specification-links.html#draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | -[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` | - - -##### 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" } - ] -} -``` - -```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" -``` - -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" } - ], - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "payload": { - "$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 -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -payload: - $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 | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format/language used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). -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](http://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message. -bindings | Map[`string`, [Message Bindings Object](#messageBindingsObject)] | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. -examples | [Map[`string`, `any`]] | An array with examples of valid message objects. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Message Trait Object Example - -```json -{ - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "contentType": "application/json" -} -``` - -```yaml -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -contentType: application/json -``` - -#### Tags Object - -A Tags object is a list of Tag Objects. - -#### Tag Object - -Allows adding meta data to a single tag. - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -name | `string` | **Required.** The name of the tag. -description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. - -This object can 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](http://spec.commonmark.org/) can be used for rich text representation. -url | `string` | **Required.** The URL for the target documentation. Value MUST be in the format of a URL. - -This object can be extended with [Specification Extensions](#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`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). - 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). - parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). - correlationIds | Map[`string`, [Correlation ID Object](#correlationIdObject)] | An object to hold reusable [Correlation ID Objects](#correlationIdObject). - operationTraits | Map[`string`, [Operation Trait Object](#operationTraitObject)] | An object to hold reusable [Operation Trait Objects](#operationTraitObject). - messageTraits | Map[`string`, [Message Trait Object](#messageTraitObject)] | An object to hold reusable [Message Trait Objects](#messageTraitObject). - serverBindings | Map[`string`, [Server Binding Object](#serverBindingsObject)] | An object to hold reusable [Server Binding Objects](#serverBindingsObject). - channelBindings | Map[`string`, [Channel Binding Object](#channelBindingsObject)] | An object to hold reusable [Channel Binding Objects](#channelBindingsObject). - operationBindings | Map[`string`, [Operation Binding Object](#operationBindingsObject)] | An object to hold reusable [Operation Binding Objects](#operationBindingsObject). - messageBindings | Map[`string`, [Message Binding Object](#messageBindingsObject)] | An object to hold reusable [Message Binding Objects](#messageBindingsObject). - -This object can 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" - } - } - } - }, - "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": { - "name": "userId", - "description": "Id of the user.", - "schema": { - "type": "string" - } - } - }, - "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 - 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: - - name: userId - description: Id of the user. - schema: - type: string - 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 -``` - -#### 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](http://json-schema.org/). - -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. - -##### 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](http://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 - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`. - -Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions in place of defining them inline. - -In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: - -##### Fixed Fields -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) | 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 can 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 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" - ], - "example": { - "name": "Puma", - "id": 1 - } -} -``` - -```yaml -type: object -properties: - id: - type: integer - format: int64 - name: - type: string -required: -- name -example: - name: Puma - id: 1 -``` - -###### 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" - ] - } - ] - } - } -} -``` - -```yaml -schemas: - Pet: - type: object - discriminator: petType - properties: - name: - type: string - petType: - type: string - required: - - name - - petType - Cat: ## "Cat" will be used as the discriminator value - description: A representation of a cat - allOf: - - $ref: '#/components/schemas/Pet' - - type: object - properties: - huntingSkill: - type: string - description: The measured skill for hunting - enum: - - clueless - - lazy - - adventurous - - aggressive - required: - - huntingSkill - Dog: ## "Dog" will be used as the discriminator value - description: A representation of a dog - allOf: - - $ref: '#/components/schemas/Pet' - - type: object - properties: - packSize: - type: integer - format: int32 - description: the size of the pack the dog is from - minimum: 0 - required: - - packSize -``` - - - - - -#### 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). - -##### 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`, and `openIdConnect`. -description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://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 a URL. - -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", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - -#### OAuth Flows Object - -Allows configuration of the supported OAuth Flows. - -##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -implicit| [OAuth Flow Object](#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 a URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### OAuth Flow Object Examples - -```JSON -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - }, - "authorizationCode": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```YAML -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your pets - authorizationCode: - authorizationUrl: https://example.com/api/oauth/dialog - tokenUrl: https://example.com/api/oauth/token - scopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - -#### Security Requirement Object - -Lists the required security schemes to execute this operation. -The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). - -When a list of Security Requirement Objects is defined on a [Server object](#serverObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the connection. - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty. - -##### Security Requirement Object Examples - -###### User/Password Security Requirement - -```json -{ - "user_pass": [] -} -``` - -```yaml -user_pass: [] -``` - -###### API Key Security Requirement - -```json -{ - "api_key": [] -} -``` - -```yaml -api_key: [] -``` - -###### OAuth2 Security Requirement - -```json -{ - "petstore_auth": [ - "write:pets", - "read:pets" - ] -} -``` - -```yaml -petstore_auth: -- write:pets -- read:pets -``` - -### Correlation ID Object - -An object that specifies an identifier at design time that can used for message tracing and correlation. - -For specifying and computing the location of a Correlation ID, a [runtime expression](#runtimeExpression) is used. - -##### Fixed Fields - -Field Name | Type | Description ----|:---|--- -description | `string` | An optional description of the identifier. [CommonMark syntax](http://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 can 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). - -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. - -### 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`](#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) -dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) -password | `string` | `password` | Used to hint UIs the input needs to be obscured. - ---- - - \ No newline at end of file diff --git a/pages/docs/reference/specification/v2.1.0.md b/pages/docs/reference/specification/v2.1.0.md deleted file mode 100644 index cba91b809334..000000000000 --- a/pages/docs/reference/specification/v2.1.0.md +++ /dev/null @@ -1,2336 +0,0 @@ -# AsyncAPI Specification - -#### Disclaimer - -Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). Mainly because **it's a great work** and we want to keep as much compatibility as possible with the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification). - -#### Version 2.1.0 - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](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 and document message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). - -The AsyncAPI Specification defines a set of files required to describe such an API. -These files can then be used to create utilities, such as documentation, integration and/or testing tools. - -The file(s) MUST describe the operations an [application](#definitionsApplication) accepts. For instance, consider the following AsyncAPI definition snippet: - -```yaml -user/signedup: - subscribe: - $ref: "#/components/messages/userSignUp" -``` - -It means that the [application](#definitionsApplication) allows [consumers](#definitionsConsumer) to subscribe to the `user/signedup` [channel](#definitionsChannel) to receive userSignUp [messages](#definitionsMessage) produced by the application. - -**The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol. - - -## Definitions - -#### Application -An application is any kind of computer program or a group of them. It MUST be a [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the server in order to connect and exchange [messages](#definitionsMessage). - -#### Producer -A producer is a type of application, connected to a server, that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the server, protocol, and use-case pattern. - -#### Consumer -A consumer is a type of application, connected to a server via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the server, protocol, and the use-case pattern. - -#### Message -A message is the mechanism by which information is exchanged via a channel between servers and applications. A message MUST contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#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, for the organization of [messages](#definitionsMessage). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume messages from channels. Servers MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the server implementation, the channel MAY be included in the message via protocol-defined headers. - -#### Protocol -A protocol is the mechanism (wireline protocol or API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, MQTT, STOMP, Mercure, WebSocket. - -#### Bindings -A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only. - -## Specification - -### Format - -The files describing the message-driven API in accordance with the AsyncAPI Specification are represented as JSON objects and conform to the JSON standards. -YAML, being a superset of JSON, can be used as well to represent a A2S (AsyncAPI Specification) file. - -For example, if a field is said to have an array value, the JSON array representation will be used: - -```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 - -The A2S representation of the API is made of a single file. -However, parts of the definitions can be split into separate files, at the discretion of the user. -This is applicable for `$ref` fields in the specification as follows from the [JSON Schema](https://json-schema.org/understanding-json-schema/structuring.html) definitions. - -By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. - -### Schema - -#### AsyncAPI Object - -This is the root document object for the API specification. -It combines resource listing and API declaration together into one document. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -asyncapi | [AsyncAPI Version String](#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) | **Required** The available channels and messages for the API. -components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. -tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. - - -This object can 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:com:smartylighting:streetlights:server" -} -``` - -```yaml -id: 'urn: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. MUST be in the format of a URL. -contact | [Contact Object](#contactObject) | The contact information for the exposed API. -license | [License Object](#licenseObject) | The license information for the exposed API. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Info Object Example: - -```json -{ - "title": "AsyncAPI Sample App", - "description": "This is a sample server.", - "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" - }, - "version": "1.0.1" -} -``` - -```yaml -title: AsyncAPI Sample App -description: This is a sample server. -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 -version: 1.0.1 -``` - -#### Contact Object - -Contact information for the exposed API. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -name | `string` | The identifying name of the contact person/organization. -url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. -email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. - -This object can be extended with [Specification Extensions](#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. MUST be in the format of a URL. - -This object can 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) | The definition of a server this application MAY connect to. - -##### Servers Object Example - -```json -{ - "production": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" - } -} -``` - -```yaml -production: - url: development.gigantic-server.com - description: Development server - protocol: kafka - protocolVersion: '1.0.0' -``` - - -#### Server Object - -An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. -protocol | `string` | **REQUIRED**. The protocol this URL supports for connection. Supported protocol include, but are not limited to: `amqp`, `amqps`, `http`, `https`, `ibmmq`, `jms`, `kafka`, `kafka-secure`, `mqtt`, `secure-mqtt`, `stomp`, `stomps`, `ws`, `wss`, `mercure`. -protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. -description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. -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. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Server Object Example - -A single server would be described as: - -```json -{ - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" -} -``` - -```yaml -url: development.gigantic-server.com -description: Development server -protocol: kafka -protocolVersion: '1.0.0' -``` - -The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): - -```json -{ - "servers": { - "development": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "staging": { - "url": "staging.gigantic-server.com", - "description": "Staging server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "production": { - "url": "api.gigantic-server.com", - "description": "Production server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - } - } -} -``` - -```yaml -servers: - development: - url: development.gigantic-server.com - description: Development server - protocol: amqp - protocolVersion: 0.9.1 - staging: - url: staging.gigantic-server.com - description: Staging server - protocol: amqp - protocolVersion: 0.9.1 - production: - url: api.gigantic-server.com - description: Production server - protocol: amqp - protocolVersion: 0.9.1 -``` - -The following shows how variables can be used for a server configuration: - -```json -{ - "servers": { - "production": { - "url": "{username}.gigantic-server.com:{port}/{basePath}", - "description": "The production API server", - "protocol": "secure-mqtt", - "variables": { - "username": { - "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" - }, - "port": { - "enum": [ - "8883", - "8884" - ], - "default": "8883" - }, - "basePath": { - "default": "v2" - } - } - } - } -} -``` - -```yaml -servers: - production: - url: '{username}.gigantic-server.com:{port}/{basePath}' - description: The production API server - protocol: secure-mqtt - variables: - username: - # note! no enum here means it is an open value - default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` - port: - enum: - - '8883' - - '8884' - default: '8883' - basePath: - # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` - default: v2 -``` - - -#### Server Variable Object - -An object representing a Server Variable for server URL template substitution. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. -default | `string` | The default value to use for substitution, and to send, if an alternate value is _not_ supplied. -description | `string` | An optional description for the server variable. [CommonMark syntax](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). - - - - - -#### 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 - -Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers. - -Channels are also known as "topics", "routing keys", "event types" or "paths". - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{channel} | [Channel Item Object](#channelItemObject) | A relative path to an individual channel. The field name MUST be in the form of a [RFC 6570 URI template](https://tools.ietf.org/html/rfc6570). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channelBindingsObject) to define them. - -##### Channels Object Example - -```json -{ - "user/signedup": { - "subscribe": { - "$ref": "#/components/messages/userSignedUp" - } - } -} -``` - -```yaml -user/signedup: - subscribe: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### Channel Item Object - -Describes the operations available on a single channel. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -$ref | `string` | Allows for an external definition of this channel item. The referenced structure MUST be in the format of a [Channel Item Object](#channelItemObject). If there are conflicts between the referenced definition and this Channel Item's definition, the behavior is *undefined*. -description | `string` | An optional description of this channel item. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation, which defines the messages produced by the application and sent to the channel. -publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation, which defines the messages consumed by the application from the channel. -parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)). -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 can be extended with [Specification Extensions](#specificationExtensions). - -##### Channel Item Object Example - -```json -{ - "description": "This channel is used to exchange messages about users signing up", - "subscribe": { - "summary": "A user signed up.", - "message": { - "description": "A longer description of the message", - "payload": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/user" - }, - "signup": { - "$ref": "#/components/schemas/signup" - } - } - } - } - }, - "bindings": { - "amqp": { - "is": "queue", - "queue": { - "exclusive": true - } - } - } -} -``` - -```yaml -description: This channel is used to exchange messages about users signing up -subscribe: - summary: A user signed up. - message: - description: A longer description of the message - payload: - type: object - properties: - user: - $ref: "#/components/schemas/user" - signup: -bindings: - amqp: - is: queue - queue: - exclusive: true -``` - -Using `oneOf` to specify multiple messages per operation: - -```json -{ - "subscribe": { - "message": { - "oneOf": [ - { "$ref": "#/components/messages/signup" }, - { "$ref": "#/components/messages/login" } - ] - } - } -} -``` - -```yaml -subscribe: - message: - oneOf: - - $ref: '#/components/messages/signup' - - $ref: '#/components/messages/login' -``` - - - - - - - -#### Operation Object - -Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. - -For example, an operation might describe a chat application use case where a user sends a text message to a group. A publish operation describes messages that are received by the chat application, whereas a subscribe operation describes messages that are sent by the chat application. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. -message | [[Message Object](#messageObject) | [Reference Object](#referenceObject)] | A definition of the message that will be published or received on this channel. `oneOf` is allowed here to specify multiple messages, however, **a message MUST be valid only against one of the referenced message objects.** - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Operation Object Example - -```json -{ - "operationId": "registerUser", - "summary": "Action to sign a user up.", - "description": "A longer description", - "tags": [ - { "name": "user" }, - { "name": "signup" }, - { "name": "register" } - ], - "message": { - "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" - } - } - } - }, - "bindings": { - "amqp": { - "ack": false - } - }, - "traits": [ - { "$ref": "#/components/operationTraits/kafka" } - ] -} -``` - -```yaml -operationId: registerUser -summary: Action to sign a user up. -description: A longer description -tags: - - name: user - - name: signup - - name: register -message: - 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" -bindings: - amqp: - ack: false -traits: - - $ref: "#/components/operationTraits/kafka" -``` - - - - -#### 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 `message` and `traits`. - -If you're looking to apply traits to a message, see the [Message Trait Object](#messageTraitObject). - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 can be extended with [Specification Extensions](#specificationExtensions). - -##### Operation Trait Object Example - -```json -{ - "bindings": { - "amqp": { - "ack": false - } - } -} -``` - -```yaml -bindings: - amqp: - ack: false -``` - - - - -#### Parameters Object - -Describes a map of parameters included in a channel name. - -This map MUST contain all the parameters used in the parent channel name. - -##### Patterned Fields - -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 name. - -##### Parameters Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - } - } - }, - "subscribe": { - "$ref": "#/components/messages/userSignedUp" - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - subscribe: - $ref: "#/components/messages/userSignedUp" -``` - - - - - -#### Parameter Object - -Describes a parameter included in a channel name. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -description | `string` | A verbose explanation of the parameter. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | Definition of the parameter. -location | `string` | A [runtime expression](#runtimeExpression) that specifies the location of the parameter value. Even when a definition for the target field exists, it MUST NOT be used to validate this parameter but, instead, the `schema` property MUST be used. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Parameter Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - }, - "location": "$message.payload#/user/id" - } - }, - "subscribe": { - "$ref": "#/components/messages/userSignedUp" - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - location: $message.payload#/user/id - subscribe: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### 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. -`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. -`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. - -This object can 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. -`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. -`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. - -This object can 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. -`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. -`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. - -This object can 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. -`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. -`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. - -This object can 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 | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -payload | `any` | Definition of the message payload. It can be of any type but defaults to [Schema object](#schemaObject). It must match the schema format, including encoding type - e.g Avro should be inlined as either a YAML or JSON object NOT a string to be parsed as YAML or JSON. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). When the payload is defined using a `$ref` to a remote file, it is RECOMMENDED the schema format includes the file encoding type to allow implementations to parse the file correctly. E.g., adding `+yaml` if content type is `application/vnd.apache.avro` results in `application/vnd.apache.avro+yaml`.

Check out the [supported schema formats table](#messageObjectSchemaFormatTable) 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](#messageObjectSchemaFormatTable). -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 API documentation control. Tags can be used for logical grouping of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 | [Map[`string`, `any`]] | An array of key/value pairs where keys MUST be either **headers** and/or **payload**. Values MUST contain examples that validate against the [headers](#messageObjectHeaders) or [payload](#messageObjectPayload) fields, respectively. Example MAY also have the **name** and **summary** additional keys to provide respectively a machine-friendly name and a short summary of what the example is about. -traits | [[Message Trait Object](#messageTraitObject) | [Reference Object](#referenceObject)] | A list of traits to apply to the message object. Traits MUST be merged into the message object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Message Object](#messageObject). - -This object can 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 2.1.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.1.0`, `application/vnd.aai.asyncapi+json;version=2.1.0`, `application/vnd.aai.asyncapi+yaml;version=2.1.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` | - - -##### 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" } - ], - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "payload": { - "$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 -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -payload: - $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 | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format/language used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). -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 API documentation control. Tags can be used for logical grouping of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 | [Map[`string`, `any`]] | An array with examples of valid message objects. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Message Trait Object Example - -```json -{ - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "contentType": "application/json" -} -``` - -```yaml -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -contentType: application/json -``` - -#### Tags Object - -A Tags object is a list of Tag Objects. - -#### Tag Object - -Allows adding meta data to a single tag. - -##### Fixed Fields -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) | Additional external documentation for this tag. - -This object can 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. Value MUST be in the format of a URL. - -This object can 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`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). - 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). - 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). - 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 can 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" - } - } - } - }, - "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.", - "schema": { - "type": "string" - } - } - }, - "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 - 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. - schema: - type: string - 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 -``` - -#### 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. - -##### 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 - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`. - -Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions in place of defining them inline. - -In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: - -##### Fixed Fields -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) | 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 can 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 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" - ], - "example": { - "name": "Puma", - "id": 1 - } -} -``` - -```yaml -type: object -properties: - id: - type: integer - format: int64 - name: - type: string -required: -- name -example: - 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 a URL. - -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", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your 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 a URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### OAuth Flow Object Examples - -```JSON -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - }, - "authorizationCode": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```YAML -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your pets - authorizationCode: - authorizationUrl: https://example.com/api/oauth/dialog - tokenUrl: https://example.com/api/oauth/token - scopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - -#### Security Requirement Object - -Lists the required security schemes to execute this operation. -The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). - -When a list of Security Requirement Objects is defined on a [Server object](#serverObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the connection. - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names. Provide scopes that are required to establish successful connection with the server. If scopes are not needed, the list can be empty. For other security scheme types, the array MUST be empty. - -##### Security Requirement Object Examples - -###### User/Password Security Requirement - -```json -{ - "user_pass": [] -} -``` - -```yaml -user_pass: [] -``` - -###### API Key Security Requirement - -```json -{ - "api_key": [] -} -``` - -```yaml -api_key: [] -``` - -###### OAuth2 Security Requirement - -```json -{ - "petstore_auth": [ - "write:pets", - "read:pets" - ] -} -``` - -```yaml -petstore_auth: -- write:pets -- read:pets -``` - -### Correlation ID Object - -An object that specifies an identifier at design time that can used for message tracing and correlation. - -For specifying and computing the location of a Correlation ID, a [runtime expression](#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 can 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). - -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. - -### 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`](#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#section-5) -dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) -password | `string` | `password` | Used to hint UIs the input needs to be obscured. - ---- - - \ No newline at end of file diff --git a/pages/docs/reference/specification/v2.2.0.md b/pages/docs/reference/specification/v2.2.0.md deleted file mode 100644 index 84991230b605..000000000000 --- a/pages/docs/reference/specification/v2.2.0.md +++ /dev/null @@ -1,2432 +0,0 @@ -# AsyncAPI Specification - -#### Disclaimer - -Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). Mainly because **it's a great work** and we want to keep as much compatibility as possible with the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification). - -#### Version 2.2.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 and document message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). - -The AsyncAPI Specification defines a set of files required to describe such an API. -These files can then be used to create utilities, such as documentation, integration and/or testing tools. - -The file(s) MUST describe the operations an [application](#definitionsApplication) accepts. For instance, consider the following AsyncAPI definition snippet: - -```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignUp" -``` - -It means that the [application](#definitionsApplication) allows [consumers](#definitionsConsumer) to subscribe to the `user/signedup` [channel](#definitionsChannel) to receive userSignUp [messages](#definitionsMessage) produced by the application. - -**The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol. - - -## Definitions - -#### Application -An application is any kind of computer program or a group of them. It MUST be a [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the server in order to connect and exchange [messages](#definitionsMessage). - -#### Producer -A producer is a type of application, connected to a server, that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the server, protocol, and use-case pattern. - -#### Consumer -A consumer is a type of application, connected to a server via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the server, protocol, and the use-case pattern. - -#### Message -A message is the mechanism by which information is exchanged via a channel between servers and applications. A message MUST contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#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, for the organization of [messages](#definitionsMessage). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume messages from channels. Servers MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the server implementation, the channel MAY be included in the message via protocol-defined headers. - -#### Protocol -A protocol is the mechanism (wireline protocol or API) by which [messages](#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, STOMP, Mercure, WebSocket. - -#### Bindings -A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only. - -## Specification - -### Format - -The files describing the message-driven API in accordance with the AsyncAPI Specification are represented as JSON objects and conform to the JSON standards. -YAML, being a superset of JSON, can be used as well to represent a A2S (AsyncAPI Specification) file. - -For example, if a field is said to have an array value, the JSON array representation will be used: - -```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. - -By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. - -### Schema - -#### AsyncAPI Object - -This is the root document object for the API specification. -It combines resource listing and API declaration together into one document. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -asyncapi | [AsyncAPI Version String](#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) | **Required** The available channels and messages for the API. -components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. -tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. - - -This object can 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:com:smartylighting:streetlights:server" -} -``` - -```yaml -id: 'urn: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. MUST be in the format of a URL. -contact | [Contact Object](#contactObject) | The contact information for the exposed API. -license | [License Object](#licenseObject) | The license information for the exposed API. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Info Object Example: - -```json -{ - "title": "AsyncAPI Sample App", - "description": "This is a sample server.", - "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" - }, - "version": "1.0.1" -} -``` - -```yaml -title: AsyncAPI Sample App -description: This is a sample server. -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 -version: 1.0.1 -``` - -#### Contact Object - -Contact information for the exposed API. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -name | `string` | The identifying name of the contact person/organization. -url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. -email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. - -This object can be extended with [Specification Extensions](#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. MUST be in the format of a URL. - -This object can 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) | The definition of a server this application MAY connect to. - -##### Servers Object Example - -```json -{ - "production": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" - } -} -``` - -```yaml -production: - url: development.gigantic-server.com - description: Development server - protocol: kafka - protocolVersion: '1.0.0' -``` - - -#### Server Object - -An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`. -protocol | `string` | **REQUIRED**. The protocol this URL supports for connection. Supported protocol include, but are not limited to: `amqp`, `amqps`, `http`, `https`, `ibmmq`, `jms`, `kafka`, `kafka-secure`, `anypointmq`, `mqtt`, `secure-mqtt`, `stomp`, `stomps`, `ws`, `wss`, `mercure`. -protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. -description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. -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. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Server Object Example - -A single server would be described as: - -```json -{ - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" -} -``` - -```yaml -url: development.gigantic-server.com -description: Development server -protocol: kafka -protocolVersion: '1.0.0' -``` - -The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): - -```json -{ - "servers": { - "development": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "staging": { - "url": "staging.gigantic-server.com", - "description": "Staging server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "production": { - "url": "api.gigantic-server.com", - "description": "Production server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - } - } -} -``` - -```yaml -servers: - development: - url: development.gigantic-server.com - description: Development server - protocol: amqp - protocolVersion: 0.9.1 - staging: - url: staging.gigantic-server.com - description: Staging server - protocol: amqp - protocolVersion: 0.9.1 - production: - url: api.gigantic-server.com - description: Production server - protocol: amqp - protocolVersion: 0.9.1 -``` - -The following shows how variables can be used for a server configuration: - -```json -{ - "servers": { - "production": { - "url": "{username}.gigantic-server.com:{port}/{basePath}", - "description": "The production API server", - "protocol": "secure-mqtt", - "variables": { - "username": { - "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" - }, - "port": { - "enum": [ - "8883", - "8884" - ], - "default": "8883" - }, - "basePath": { - "default": "v2" - } - } - } - } -} -``` - -```yaml -servers: - production: - url: '{username}.gigantic-server.com:{port}/{basePath}' - description: The production API server - protocol: secure-mqtt - variables: - username: - # note! no enum here means it is an open value - default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` - port: - enum: - - '8883' - - '8884' - default: '8883' - basePath: - # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` - default: v2 -``` - - -#### Server Variable Object - -An object representing a Server Variable for server URL template substitution. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. -default | `string` | The default value to use for substitution, and to send, if an alternate value is _not_ supplied. -description | `string` | An optional description for the server variable. [CommonMark syntax](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). - - - - - -#### 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 - -Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers. - -Channels are also known as "topics", "routing keys", "event types" or "paths". - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{channel} | [Channel Item Object](#channelItemObject) | A relative path to an individual channel. The field name MUST be in the form of a [RFC 6570 URI template](https://tools.ietf.org/html/rfc6570). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channelBindingsObject) to define them. - -##### Channels Object Example - -```json -{ - "user/signedup": { - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### Channel Item Object - -Describes the operations available on a single channel. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -$ref | `string` | Allows for an external definition of this channel item. The referenced structure MUST be in the format of a [Channel Item Object](#channelItemObject). If there are conflicts between the referenced definition and this Channel Item's definition, the behavior is *undefined*. -description | `string` | An optional description of this channel item. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). -subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation, which defines the messages produced by the application and sent to the channel. -publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation, which defines the messages consumed by the application from the channel. -parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)). -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 can be extended with [Specification Extensions](#specificationExtensions). - -##### Channel Item Object Example - -```json -{ - "description": "This channel is used to exchange messages about users signing up", - "subscribe": { - "summary": "A user signed up.", - "message": { - "description": "A longer description of the message", - "payload": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/user" - }, - "signup": { - "$ref": "#/components/schemas/signup" - } - } - } - } - }, - "bindings": { - "amqp": { - "is": "queue", - "queue": { - "exclusive": true - } - } - } -} -``` - -```yaml -description: This channel is used to exchange messages about users signing up -subscribe: - summary: A user signed up. - message: - description: A longer description of the message - payload: - type: object - properties: - user: - $ref: "#/components/schemas/user" - signup: -bindings: - amqp: - is: queue - queue: - exclusive: true -``` - -Using `oneOf` to specify multiple messages per operation: - -```json -{ - "subscribe": { - "message": { - "oneOf": [ - { "$ref": "#/components/messages/signup" }, - { "$ref": "#/components/messages/login" } - ] - } - } -} -``` - -```yaml -subscribe: - message: - oneOf: - - $ref: '#/components/messages/signup' - - $ref: '#/components/messages/login' -``` - - -Using explicit by-name references to the servers on which the channel is available: - -```json -{ - "description": "This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments.", - "servers": [ - "rabbitmqBrokerInProd", - "rabbitmqBrokerInStaging", - ], - "subscribe": { - "message": { - "$ref": "#/components/messages/WebUICommand" - } - }, - "bindings": { - "amqp": { - "is": "queue" - } - } -} -``` - -```yaml -description: This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments. -servers: - - rabbitmqBrokerInProd - - rabbitmqBrokerInStaging -subscribe: - message: - $ref: "#/components/messages/WebUICommand" -bindings: - amqp: - is: queue -``` - - - - - -#### Operation Object - -Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. - -For example, an operation might describe a chat application use case where a user sends a text message to a group. A publish operation describes messages that are received by the chat application, whereas a subscribe operation describes messages that are sent by the chat application. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. -message | [[Message Object](#messageObject) | [Reference Object](#referenceObject)] | A definition of the message that will be published or received on this channel. `oneOf` is allowed here to specify multiple messages, however, **a message MUST be valid only against one of the referenced message objects.** - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Operation Object Example - -```json -{ - "operationId": "registerUser", - "summary": "Action to sign a user up.", - "description": "A longer description", - "tags": [ - { "name": "user" }, - { "name": "signup" }, - { "name": "register" } - ], - "message": { - "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" - } - } - } - }, - "bindings": { - "amqp": { - "ack": false - } - }, - "traits": [ - { "$ref": "#/components/operationTraits/kafka" } - ] -} -``` - -```yaml -operationId: registerUser -summary: Action to sign a user up. -description: A longer description -tags: - - name: user - - name: signup - - name: register -message: - 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" -bindings: - amqp: - ack: false -traits: - - $ref: "#/components/operationTraits/kafka" -``` - - - - -#### 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 `message` and `traits`. - -If you're looking to apply traits to a message, see the [Message Trait Object](#messageTraitObject). - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 can be extended with [Specification Extensions](#specificationExtensions). - -##### Operation Trait Object Example - -```json -{ - "bindings": { - "amqp": { - "ack": false - } - } -} -``` - -```yaml -bindings: - amqp: - ack: false -``` - - - - -#### Parameters Object - -Describes a map of parameters included in a channel name. - -This map MUST contain all the parameters used in the parent channel name. - -##### Patterned Fields - -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 name. - -##### Parameters Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - } - } - }, - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - - -#### Parameter Object - -Describes a parameter included in a channel name. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -description | `string` | A verbose explanation of the parameter. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | Definition of the parameter. -location | `string` | A [runtime expression](#runtimeExpression) that specifies the location of the parameter value. Even when a definition for the target field exists, it MUST NOT be used to validate this parameter but, instead, the `schema` property MUST be used. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Parameter Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - }, - "location": "$message.payload#/user/id" - } - }, - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - location: $message.payload#/user/id - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### 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. -`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. - -This object can 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. -`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. - -This object can 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. -`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. - -This object can 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. -`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. - -This object can 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 | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -payload | `any` | Definition of the message payload. It can be of any type but defaults to [Schema object](#schemaObject). It must match the schema format, including encoding type - e.g Avro should be inlined as either a YAML or JSON object NOT a string to be parsed as YAML or JSON. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). When the payload is defined using a `$ref` to a remote file, it is RECOMMENDED the schema format includes the file encoding type to allow implementations to parse the file correctly. E.g., adding `+yaml` if content type is `application/vnd.apache.avro` results in `application/vnd.apache.avro+yaml`.

Check out the [supported schema formats table](#messageObjectSchemaFormatTable) 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](#messageObjectSchemaFormatTable). -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 API documentation control. Tags can be used for logical grouping of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 into the message object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Message Object](#messageObject). - -This object can 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 2.2.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.2.0`, `application/vnd.aai.asyncapi+json;version=2.2.0`, `application/vnd.aai.asyncapi+yaml;version=2.2.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` | - - -##### 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" } - ], - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "payload": { - "$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 -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -payload: - $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 | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format/language used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). -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 API documentation control. Tags can be used for logical grouping of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 can be extended with [Specification Extensions](#specificationExtensions). - -##### Message Trait Object Example - -```json -{ - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "contentType": "application/json" -} -``` - -```yaml -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -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 | `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 can 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. - -#### 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) | Additional external documentation for this tag. - -This object can 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. Value MUST be in the format of a URL. - -This object can 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`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). - 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). - 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). - 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 can 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" - } - } - } - }, - "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.", - "schema": { - "type": "string" - } - } - }, - "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 - 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. - schema: - type: string - 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 -``` - -#### 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. - -##### 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 - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`. - -Alternatively, any time a Schema Object can be used, a [Reference Object](#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) | 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 can 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 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" - ], - "example": { - "name": "Puma", - "id": 1 - } -} -``` - -```yaml -type: object -properties: - id: - type: integer - format: int64 - name: - type: string -required: -- name -example: - 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 a URL. - -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", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your 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 a URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### OAuth Flow Object Examples - -```JSON -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - }, - "authorizationCode": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```YAML -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your pets - authorizationCode: - authorizationUrl: https://example.com/api/oauth/dialog - tokenUrl: https://example.com/api/oauth/token - scopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - -#### Security Requirement Object - -Lists the required security schemes to execute this operation. -The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). - -When a list of Security Requirement Objects is defined on a [Server object](#serverObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the connection. - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names. Provide scopes that are required to establish successful connection with the server. If scopes are not needed, the list can be empty. For other security scheme types, the array MUST be empty. - -##### Security Requirement Object Examples - -###### User/Password Security Requirement - -```json -{ - "user_pass": [] -} -``` - -```yaml -user_pass: [] -``` - -###### API Key Security Requirement - -```json -{ - "api_key": [] -} -``` - -```yaml -api_key: [] -``` - -###### OAuth2 Security Requirement - -```json -{ - "petstore_auth": [ - "write:pets", - "read:pets" - ] -} -``` - -```yaml -petstore_auth: -- write:pets -- read:pets -``` - -### Correlation ID Object - -An object that specifies an identifier at design time that can used for message tracing and correlation. - -For specifying and computing the location of a Correlation ID, a [runtime expression](#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 can 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). - -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. - -### 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`](#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#section-5) -dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) -password | `string` | `password` | Used to hint UIs the input needs to be obscured. - ---- - - \ No newline at end of file diff --git a/pages/docs/reference/specification/v2.3.0.md b/pages/docs/reference/specification/v2.3.0.md deleted file mode 100644 index ad5ee294b3e1..000000000000 --- a/pages/docs/reference/specification/v2.3.0.md +++ /dev/null @@ -1,2453 +0,0 @@ -# AsyncAPI Specification - -#### Disclaimer - -Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). Mainly because **it's a great work** and we want to keep as much compatibility as possible with the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification). - -#### Version 2.3.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 and document message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). - -The AsyncAPI Specification defines a set of files required to describe such an API. -These files can then be used to create utilities, such as documentation, integration and/or testing tools. - -The file(s) MUST describe the operations an [application](#definitionsApplication) accepts. For instance, consider the following AsyncAPI definition snippet: - -```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignUp" -``` - -It means that the [application](#definitionsApplication) allows [consumers](#definitionsConsumer) to subscribe to the `user/signedup` [channel](#definitionsChannel) to receive userSignUp [messages](#definitionsMessage) produced by the application. - -**The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol. - - -## Definitions - -#### Application -An application is any kind of computer program or a group of them. It MUST be a [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the server in order to connect and exchange [messages](#definitionsMessage). - -#### Producer -A producer is a type of application, connected to a server, that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the server, protocol, and use-case pattern. - -#### Consumer -A consumer is a type of application, connected to a server via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the server, protocol, and the use-case pattern. - -#### Message -A message is the mechanism by which information is exchanged via a channel between servers and applications. A message MUST contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#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, for the organization of [messages](#definitionsMessage). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume messages from channels. Servers MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the server implementation, the channel MAY be included in the message via protocol-defined headers. - -#### Protocol -A protocol is the mechanism (wireline protocol or API) by which [messages](#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. - -#### 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. - -By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. - -### Schema - -#### AsyncAPI Object - -This is the root document object for the API specification. -It combines resource listing and API declaration together into one document. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -asyncapi | [AsyncAPI Version String](#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) | **Required** The available channels and messages for the API. -components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. -tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. - - -This object can 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:com:smartylighting:streetlights:server" -} -``` - -```yaml -id: 'urn: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. MUST be in the format of a URL. -contact | [Contact Object](#contactObject) | The contact information for the exposed API. -license | [License Object](#licenseObject) | The license information for the exposed API. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Info Object Example: - -```json -{ - "title": "AsyncAPI Sample App", - "description": "This is a sample server.", - "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" - }, - "version": "1.0.1" -} -``` - -```yaml -title: AsyncAPI Sample App -description: This is a sample server. -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 -version: 1.0.1 -``` - -#### Contact Object - -Contact information for the exposed API. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -name | `string` | The identifying name of the contact person/organization. -url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. -email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. - -This object can be extended with [Specification Extensions](#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. MUST be in the format of a URL. - -This object can 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) | The definition of a server this application MAY connect to. - -##### Servers Object Example - -```json -{ - "production": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" - } -} -``` - -```yaml -production: - url: development.gigantic-server.com - description: Development server - protocol: kafka - protocolVersion: '1.0.0' -``` - - -#### Server Object - -An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. -protocol | `string` | **REQUIRED**. The protocol this URL supports for connection. Supported protocol include, but are not limited to: `amqp`, `amqps`, `http`, `https`, `ibmmq`, `jms`, `kafka`, `kafka-secure`, `anypointmq`, `mqtt`, `secure-mqtt`, `solace`, `stomp`, `stomps`, `ws`, `wss`, `mercure`. -protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. -description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. -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. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Server Object Example - -A single server would be described as: - -```json -{ - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" -} -``` - -```yaml -url: development.gigantic-server.com -description: Development server -protocol: kafka -protocolVersion: '1.0.0' -``` - -The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): - -```json -{ - "servers": { - "development": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "staging": { - "url": "staging.gigantic-server.com", - "description": "Staging server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "production": { - "url": "api.gigantic-server.com", - "description": "Production server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - } - } -} -``` - -```yaml -servers: - development: - url: development.gigantic-server.com - description: Development server - protocol: amqp - protocolVersion: 0.9.1 - staging: - url: staging.gigantic-server.com - description: Staging server - protocol: amqp - protocolVersion: 0.9.1 - production: - url: api.gigantic-server.com - description: Production server - protocol: amqp - protocolVersion: 0.9.1 -``` - -The following shows how variables can be used for a server configuration: - -```json -{ - "servers": { - "production": { - "url": "{username}.gigantic-server.com:{port}/{basePath}", - "description": "The production API server", - "protocol": "secure-mqtt", - "variables": { - "username": { - "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" - }, - "port": { - "enum": [ - "8883", - "8884" - ], - "default": "8883" - }, - "basePath": { - "default": "v2" - } - } - } - } -} -``` - -```yaml -servers: - production: - url: '{username}.gigantic-server.com:{port}/{basePath}' - description: The production API server - protocol: secure-mqtt - variables: - username: - # note! no enum here means it is an open value - default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` - port: - enum: - - '8883' - - '8884' - default: '8883' - basePath: - # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` - default: v2 -``` - - -#### Server Variable Object - -An object representing a Server Variable for server URL template substitution. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. -default | `string` | The default value to use for substitution, and to send, if an alternate value is _not_ supplied. -description | `string` | An optional description for the server variable. [CommonMark syntax](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). - - - - - -#### 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 - -Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers. - -Channels are also known as "topics", "routing keys", "event types" or "paths". - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{channel} | [Channel Item Object](#channelItemObject) | A relative path to an individual channel. The field name MUST be in the form of a [RFC 6570 URI template](https://tools.ietf.org/html/rfc6570). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channelBindingsObject) to define them. - -##### Channels Object Example - -```json -{ - "user/signedup": { - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### Channel Item Object - -Describes the operations available on a single channel. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -$ref | `string` | Allows for an external definition of this channel item. The referenced structure MUST be in the format of a [Channel Item Object](#channelItemObject). If there are conflicts between the referenced definition and this Channel Item's definition, the behavior is *undefined*.

**Deprecated:** Usage of the `$ref` property has been deprecated. -description | `string` | An optional description of this channel item. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). -subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation, which defines the messages produced by the application and sent to the channel. -publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation, which defines the messages consumed by the application from the channel. -parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)). -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 can be extended with [Specification Extensions](#specificationExtensions). - -##### Channel Item Object Example - -```json -{ - "description": "This channel is used to exchange messages about users signing up", - "subscribe": { - "summary": "A user signed up.", - "message": { - "description": "A longer description of the message", - "payload": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/user" - }, - "signup": { - "$ref": "#/components/schemas/signup" - } - } - } - } - }, - "bindings": { - "amqp": { - "is": "queue", - "queue": { - "exclusive": true - } - } - } -} -``` - -```yaml -description: This channel is used to exchange messages about users signing up -subscribe: - summary: A user signed up. - message: - description: A longer description of the message - payload: - type: object - properties: - user: - $ref: "#/components/schemas/user" - signup: - $ref: "#/components/schemas/signup" -bindings: - amqp: - is: queue - queue: - exclusive: true -``` - -Using `oneOf` to specify multiple messages per operation: - -```json -{ - "subscribe": { - "message": { - "oneOf": [ - { "$ref": "#/components/messages/signup" }, - { "$ref": "#/components/messages/login" } - ] - } - } -} -``` - -```yaml -subscribe: - message: - oneOf: - - $ref: '#/components/messages/signup' - - $ref: '#/components/messages/login' -``` - - -Using explicit by-name references to the servers on which the channel is available: - -```json -{ - "description": "This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments.", - "servers": [ - "rabbitmqBrokerInProd", - "rabbitmqBrokerInStaging", - ], - "subscribe": { - "message": { - "$ref": "#/components/messages/WebUICommand" - } - }, - "bindings": { - "amqp": { - "is": "queue" - } - } -} -``` - -```yaml -description: This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments. -servers: - - rabbitmqBrokerInProd - - rabbitmqBrokerInStaging -subscribe: - message: - $ref: "#/components/messages/WebUICommand" -bindings: - amqp: - is: queue -``` - - - - - -#### Operation Object - -Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. - -For example, an operation might describe a chat application use case where a user sends a text message to a group. A publish operation describes messages that are received by the chat application, whereas a subscribe operation describes messages that are sent by the chat application. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. -message | [Message Object](#messageObject) | [Reference Object](#referenceObject) | Map["oneOf", [[Message Object](#messageObject) | [Reference Object](#referenceObject)]] | A definition of the message that will be published or received by this operation. Map containing a single `oneOf` key is allowed here to specify multiple messages. However, **a message MUST be valid only against one of the message objects.** - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Operation Object Example - -```json -{ - "operationId": "registerUser", - "summary": "Action to sign a user up.", - "description": "A longer description", - "tags": [ - { "name": "user" }, - { "name": "signup" }, - { "name": "register" } - ], - "message": { - "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" - } - } - } - }, - "bindings": { - "amqp": { - "ack": false - } - }, - "traits": [ - { "$ref": "#/components/operationTraits/kafka" } - ] -} -``` - -```yaml -operationId: registerUser -summary: Action to sign a user up. -description: A longer description -tags: - - name: user - - name: signup - - name: register -message: - 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" -bindings: - amqp: - ack: false -traits: - - $ref: "#/components/operationTraits/kafka" -``` - - - - -#### 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 `message` and `traits`. - -If you're looking to apply traits to a message, see the [Message Trait Object](#messageTraitObject). - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 can be extended with [Specification Extensions](#specificationExtensions). - -##### Operation Trait Object Example - -```json -{ - "bindings": { - "amqp": { - "ack": false - } - } -} -``` - -```yaml -bindings: - amqp: - ack: false -``` - - - - -#### Parameters Object - -Describes a map of parameters included in a channel name. - -This map MUST contain all the parameters used in the parent channel name. - -##### Patterned Fields - -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 name. - -##### Parameters Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - } - } - }, - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - - -#### Parameter Object - -Describes a parameter included in a channel name. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -description | `string` | A verbose explanation of the parameter. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | Definition of the parameter. -location | `string` | A [runtime expression](#runtimeExpression) that specifies the location of the parameter value. Even when a definition for the target field exists, it MUST NOT be used to validate this parameter but, instead, the `schema` property MUST be used. - -This object can be extended with [Specification Extensions](#specificationExtensions). - -##### Parameter Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - }, - "location": "$message.payload#/user/id" - } - }, - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - location: $message.payload#/user/id - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### 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. - -This object can 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. - -This object can 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. - -This object can 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. - -This object can 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 | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -payload | `any` | Definition of the message payload. It can be of any type but defaults to [Schema object](#schemaObject). It must match the schema format, including encoding type - e.g Avro should be inlined as either a YAML or JSON object NOT a string to be parsed as YAML or JSON. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). When the payload is defined using a `$ref` to a remote file, it is RECOMMENDED the schema format includes the file encoding type to allow implementations to parse the file correctly. E.g., adding `+yaml` if content type is `application/vnd.apache.avro` results in `application/vnd.apache.avro+yaml`.

Check out the [supported schema formats table](#messageObjectSchemaFormatTable) 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](#messageObjectSchemaFormatTable). -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 API documentation control. Tags can be used for logical grouping of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 into the message object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Message Object](#messageObject). - -This object can 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 2.3.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.3.0`, `application/vnd.aai.asyncapi+json;version=2.3.0`, `application/vnd.aai.asyncapi+yaml;version=2.3.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` | - - -##### 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" } - ], - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "payload": { - "$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 -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -payload: - $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 | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format/language used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). -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 API documentation control. Tags can be used for logical grouping of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 can be extended with [Specification Extensions](#specificationExtensions). - -##### Message Trait Object Example - -```json -{ - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "contentType": "application/json" -} -``` - -```yaml -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -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 | `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 can 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. - -#### 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) | Additional external documentation for this tag. - -This object can 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. Value MUST be in the format of a URL. - -This object can 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`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). - servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject). - channels | Map[`string`, [Channel Item Object](#channelItemObject)] | An object to hold reusable [Channel Item Objects](#channelItemObject). - 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). - 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). - 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 can 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" - } - } - } - }, - "servers": { - "development": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - } - }, - "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.", - "schema": { - "type": "string" - } - } - }, - "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 - servers: - development: - url: development.gigantic-server.com - description: Development server - protocol: amqp - protocolVersion: 0.9.1 - 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. - schema: - type: string - 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 -``` - -#### 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. - -##### 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 - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`. - -Alternatively, any time a Schema Object can be used, a [Reference Object](#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) | 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 can 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 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" - ], - "example": { - "name": "Puma", - "id": 1 - } -} -``` - -```yaml -type: object -properties: - id: - type: integer - format: int64 - name: - type: string -required: -- name -example: - 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 a URL. - -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", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your 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 a URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### OAuth Flow Object Examples - -```JSON -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - }, - "authorizationCode": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```YAML -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your pets - authorizationCode: - authorizationUrl: https://example.com/api/oauth/dialog - tokenUrl: https://example.com/api/oauth/token - scopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - -#### Security Requirement Object - -Lists the required security schemes to execute this operation. -The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). - -When a list of Security Requirement Objects is defined on a [Server object](#serverObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the connection. - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names. Provide scopes that are required to establish successful connection with the server. If scopes are not needed, the list can be empty. For other security scheme types, the array MUST be empty. - -##### Security Requirement Object Examples - -###### User/Password Security Requirement - -```json -{ - "user_pass": [] -} -``` - -```yaml -user_pass: [] -``` - -###### API Key Security Requirement - -```json -{ - "api_key": [] -} -``` - -```yaml -api_key: [] -``` - -###### OAuth2 Security Requirement - -```json -{ - "petstore_auth": [ - "write:pets", - "read:pets" - ] -} -``` - -```yaml -petstore_auth: -- write:pets -- read:pets -``` - -### Correlation ID Object - -An object that specifies an identifier at design time that can used for message tracing and correlation. - -For specifying and computing the location of a Correlation ID, a [runtime expression](#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 can 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). - -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. - -### 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`](#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) -dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) -password | `string` | `password` | Used to hint UIs the input needs to be obscured. - - - diff --git a/pages/docs/reference/specification/v2.4.0.md b/pages/docs/reference/specification/v2.4.0.md deleted file mode 100644 index b74266160138..000000000000 --- a/pages/docs/reference/specification/v2.4.0.md +++ /dev/null @@ -1,2510 +0,0 @@ -# AsyncAPI Specification - -#### Disclaimer - -Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). Mainly because **it's a great work** and we want to keep as much compatibility as possible with the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification). - -#### Version 2.4.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 and document message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). - -The AsyncAPI Specification defines a set of files required to describe such an API. -These files can then be used to create utilities, such as documentation, integration and/or testing tools. - -The file(s) MUST describe the operations an [application](#definitionsApplication) accepts. For instance, consider the following AsyncAPI definition snippet: - -```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignUp" -``` - -It means that the [application](#definitionsApplication) allows [consumers](#definitionsConsumer) to subscribe to the `user/signedup` [channel](#definitionsChannel) to receive userSignUp [messages](#definitionsMessage) produced by the application. - -**The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol. - - -## Definitions - -#### Server -A server MAY be a message broker that is capable of sending and/or receiving between a [producer](#definitionsProducer) and [consumer](#definitionsConsumer). 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 [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the [server](#definitionsServer) in order to connect and exchange [messages](#definitionsMessage). - -#### Producer -A producer is a type of application, connected to a [server](#definitionsServer), that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the [server](#definitionsServer), protocol, and use-case pattern. - -#### Consumer -A consumer is a type of application, connected to a [server](#definitionsServer) via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. - -#### Message -A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MUST 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). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume 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. - -#### 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. - -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) | **REQUIRED** The available channels and messages for the API. -components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. -tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. - - -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. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Info Object Example: - -```json -{ - "title": "AsyncAPI Sample App", - "description": "This is a sample server.", - "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" - }, - "version": "1.0.1" -} -``` - -```yaml -title: AsyncAPI Sample App -description: This is a sample server. -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 -version: 1.0.1 -``` - -#### Contact Object - -Contact information for the exposed API. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -name | `string` | The identifying name of the contact person/organization. -url | `string` | The URL pointing to the contact information. 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 -{ - "production": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" - } -} -``` - -```yaml -production: - url: development.gigantic-server.com - description: Development server - protocol: kafka - protocolVersion: '1.0.0' -``` - - -#### Server Object - -An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. -protocol | `string` | **REQUIRED**. The protocol this URL supports for connection. Supported protocol include, but are not limited to: `amqp`, `amqps`, `http`, `https`, `ibmmq`, `jms`, `kafka`, `kafka-secure`, `anypointmq`, `mqtt`, `secure-mqtt`, `solace`, `stomp`, `stomps`, `ws`, `wss`, `mercure`. -protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. -description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. -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. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Server Object Example - -A single server would be described as: - -```json -{ - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" -} -``` - -```yaml -url: development.gigantic-server.com -description: Development server -protocol: kafka -protocolVersion: '1.0.0' -``` - -The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): - -```json -{ - "servers": { - "development": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "staging": { - "url": "staging.gigantic-server.com", - "description": "Staging server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - }, - "production": { - "url": "api.gigantic-server.com", - "description": "Production server", - "protocol": "amqp", - "protocolVersion": "0.9.1" - } - } -} -``` - -```yaml -servers: - development: - url: development.gigantic-server.com - description: Development server - protocol: amqp - protocolVersion: 0.9.1 - staging: - url: staging.gigantic-server.com - description: Staging server - protocol: amqp - protocolVersion: 0.9.1 - production: - url: api.gigantic-server.com - description: Production server - protocol: amqp - protocolVersion: 0.9.1 -``` - -The following shows how variables can be used for a server configuration: - -```json -{ - "servers": { - "production": { - "url": "{username}.gigantic-server.com:{port}/{basePath}", - "description": "The production API server", - "protocol": "secure-mqtt", - "variables": { - "username": { - "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" - }, - "port": { - "enum": [ - "8883", - "8884" - ], - "default": "8883" - }, - "basePath": { - "default": "v2" - } - } - } - } -} -``` - -```yaml -servers: - production: - url: '{username}.gigantic-server.com:{port}/{basePath}' - description: The production API server - protocol: secure-mqtt - variables: - username: - # note! no enum here means it is an open value - default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` - port: - enum: - - '8883' - - '8884' - default: '8883' - basePath: - # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` - default: v2 -``` - - -#### Server Variable Object - -An object representing a Server Variable for server URL template substitution. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. -default | `string` | The default value to use for substitution, and to send, if an alternate value is _not_ supplied. -description | `string` | An optional description for the server variable. [CommonMark syntax](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). - - - - - -#### 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 - -Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers. - -Channels are also known as "topics", "routing keys", "event types" or "paths". - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{channel} | [Channel Item Object](#channelItemObject) | A relative path to an individual channel. The field name MUST be in the form of a [RFC 6570 URI template](https://tools.ietf.org/html/rfc6570). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channelBindingsObject) to define them. - -##### Channels Object Example - -```json -{ - "user/signedup": { - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### Channel Item Object - -Describes the operations available on a single channel. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -$ref | `string` | Allows for a referenced definition of this channel item. The referenced structure MUST be in the form of a [Channel Item Object](#channelItemObject). In case a Channel Item Object field appears both in the defined object and the referenced object, the behavior is *undefined*. Resolution is done as defined by the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03).

**Deprecated:** Usage of the `$ref` property has been deprecated. -description | `string` | An optional description of this channel item. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). -subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation, which defines the messages produced by the application and sent to the channel. -publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation, which defines the messages consumed by the application from the channel. -parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)). -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 Item Object Example - -```json -{ - "description": "This channel is used to exchange messages about users signing up", - "subscribe": { - "summary": "A user signed up.", - "message": { - "description": "A longer description of the message", - "payload": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/user" - }, - "signup": { - "$ref": "#/components/schemas/signup" - } - } - } - } - }, - "bindings": { - "amqp": { - "is": "queue", - "queue": { - "exclusive": true - } - } - } -} -``` - -```yaml -description: This channel is used to exchange messages about users signing up -subscribe: - summary: A user signed up. - message: - description: A longer description of the message - payload: - type: object - properties: - user: - $ref: "#/components/schemas/user" - signup: - $ref: "#/components/schemas/signup" -bindings: - amqp: - is: queue - queue: - exclusive: true -``` - -Using `oneOf` to specify multiple messages per operation: - -```json -{ - "subscribe": { - "message": { - "oneOf": [ - { "$ref": "#/components/messages/signup" }, - { "$ref": "#/components/messages/login" } - ] - } - } -} -``` - -```yaml -subscribe: - message: - oneOf: - - $ref: '#/components/messages/signup' - - $ref: '#/components/messages/login' -``` - - -Using explicit by-name references to the servers on which the channel is available: - -```json -{ - "description": "This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments.", - "servers": [ - "rabbitmqBrokerInProd", - "rabbitmqBrokerInStaging", - ], - "subscribe": { - "message": { - "$ref": "#/components/messages/WebUICommand" - } - }, - "bindings": { - "amqp": { - "is": "queue" - } - } -} -``` - -```yaml -description: This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments. -servers: - - rabbitmqBrokerInProd - - rabbitmqBrokerInStaging -subscribe: - message: - $ref: "#/components/messages/WebUICommand" -bindings: - amqp: - is: queue -``` - - - - - -#### Operation Object - -Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. - -For example, an operation might describe a chat application use case where a user sends a text message to a group. A publish operation describes messages that are received by the chat application, whereas a subscribe operation describes messages that are sent by the chat application. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. -message | [Message Object](#messageObject) | [Reference Object](#referenceObject) | Map["oneOf", [[Message Object](#messageObject) | [Reference Object](#referenceObject)]] | A definition of the message that will be published or received by this operation. Map containing a single `oneOf` key is allowed here to specify multiple messages. However, **a message MUST be valid only against one of the message objects.** - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Operation Object Example - -```json -{ - "operationId": "registerUser", - "summary": "Action to sign a user up.", - "description": "A longer description", - "security": [ - { - "petstore_auth": [ - "write:pets", - "read:pets" - ] - } - ], - "tags": [ - { "name": "user" }, - { "name": "signup" }, - { "name": "register" } - ], - "message": { - "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" - } - } - } - }, - "bindings": { - "amqp": { - "ack": false - } - }, - "traits": [ - { "$ref": "#/components/operationTraits/kafka" } - ] -} -``` - -```yaml -operationId: registerUser -summary: Action to sign a user up. -description: A longer description -security: - - petstore_auth: - - write:pets - - read:pets -tags: - - name: user - - name: signup - - name: register -message: - 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" -bindings: - amqp: - ack: false -traits: - - $ref: "#/components/operationTraits/kafka" -``` - - - - -#### 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 `message` and `traits`. - -If you're looking to apply traits to a message, see the [Message Trait Object](#messageTraitObject). - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied. -tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 -``` - - - - -#### Parameters Object - -Describes a map of parameters included in a channel name. - -This map MUST contain all the parameters used in the parent channel name. - -##### Patterned Fields - -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 name. - -##### Parameters Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - } - } - }, - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - - -#### Parameter Object - -Describes a parameter included in a channel name. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -description | `string` | A verbose explanation of the parameter. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | Definition of the parameter. -location | `string` | A [runtime expression](#runtimeExpression) that specifies the location of the parameter value. Even when a definition for the target field exists, it MUST NOT be used to validate this parameter but, instead, the `schema` property MUST be used. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Parameter Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - }, - "location": "$message.payload#/user/id" - } - }, - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - location: $message.payload#/user/id - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### 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. - -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. - -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. - -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. - -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 ----|:---:|--- -messageId | `string` | Unique string used to identify the message. The id MUST be unique among all messages described in the API. The messageId value is **case-sensitive**. Tools and libraries MAY use the messageId to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. -headers | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -payload | `any` | Definition of the message payload. It can be of any type but defaults to [Schema object](#schemaObject). It must match the schema format, including encoding type - e.g Avro should be inlined as either a YAML or JSON object NOT a string to be parsed as YAML or JSON. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). When the payload is defined using a `$ref` to a remote file, it is RECOMMENDED the schema format includes the file encoding type to allow implementations to parse the file correctly. E.g., adding `+yaml` if content type is `application/vnd.apache.avro` results in `application/vnd.apache.avro+yaml`.

Check out the [supported schema formats table](#messageObjectSchemaFormatTable) 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](#messageObjectSchemaFormatTable). -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 API documentation control. Tags can be used for logical grouping of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 into the message object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Message Object](#messageObject). - -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 2.4.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.4.0`, `application/vnd.aai.asyncapi+json;version=2.4.0`, `application/vnd.aai.asyncapi+yaml;version=2.4.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` | - - -##### Message Object Example - -```json -{ - "messageId": "userSignup", - "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 -messageId: userSignup -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 -{ - "messageId": "userSignup", - "name": "UserSignup", - "title": "User signup", - "summary": "Action to sign a user up.", - "description": "A longer description", - "tags": [ - { "name": "user" }, - { "name": "signup" }, - { "name": "register" } - ], - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "payload": { - "$ref": "path/to/user-create.avsc#/UserCreate" - } -} -``` - -```yaml -messageId: userSignup -name: UserSignup -title: User signup -summary: Action to sign a user up. -description: A longer description -tags: - - name: user - - name: signup - - name: register -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -payload: - $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 ----|:---:|--- -messageId | `string` | Unique string used to identify the message. The id MUST be unique among all messages described in the API. The messageId value is **case-sensitive**. Tools and libraries MAY use the messageId to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. -headers | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format/language used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). -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 API documentation control. Tags can be used for logical grouping of messages. -externalDocs | [External Documentation Object](#externalDocumentationObject) | 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 -{ - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "contentType": "application/json" -} -``` - -```yaml -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -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 | `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. - -#### 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) | 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`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). - servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject). - serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). - channels | Map[`string`, [Channel Item Object](#channelItemObject)] | An object to hold reusable [Channel Item Objects](#channelItemObject). - 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). - 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). - 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" - } - } - } - }, - "servers": { - "development": { - "url": "{stage}.gigantic-server.com:{port}", - "description": "Development server", - "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 `gigantic-server.com`" - }, - "port": { - "enum": ["8883", "8884"], - "default": "8883" - } - }, - "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.", - "schema": { - "type": "string" - } - } - }, - "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 - servers: - development: - url: "{stage}.gigantic-server.com:{port}" - description: Development server - 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 `gigantic-server.com` - port: - enum: [8883, 8884] - default: 8883 - 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. - schema: - type: string - 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 -``` - -#### 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. - -##### 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 - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`. - -Alternatively, any time a Schema Object can be used, a [Reference Object](#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) | 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 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. - -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", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your 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. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### OAuth Flow Object Examples - -```JSON -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - }, - "authorizationCode": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```YAML -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your pets - authorizationCode: - authorizationUrl: https://example.com/api/oauth/dialog - tokenUrl: https://example.com/api/oauth/token - scopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - -#### Security Requirement Object - -Lists the required security schemes to execute this operation. -The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). - -When a list of Security Requirement Objects is defined on a [Server object](#serverObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the connection. - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names. Provide scopes that are required to establish successful connection with the server. If scopes are not needed, the list can be empty. For other security scheme types, the array MUST be empty. - -##### Security Requirement Object Examples - -###### User/Password Security Requirement - -```json -{ - "user_pass": [] -} -``` - -```yaml -user_pass: [] -``` - -###### API Key Security Requirement - -```json -{ - "api_key": [] -} -``` - -```yaml -api_key: [] -``` - -###### OAuth2 Security Requirement - -```json -{ - "petstore_auth": [ - "write:pets", - "read:pets" - ] -} -``` - -```yaml -petstore_auth: -- write:pets -- read:pets -``` - -### Correlation ID Object - -An object that specifies an identifier at design time that can used for message tracing and correlation. - -For specifying and computing the location of a Correlation ID, a [runtime expression](#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). - -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. - -### 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`](#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#section-5) -dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5) -password | `string` | `password` | Used to hint UIs the input needs to be obscured. diff --git a/pages/docs/reference/specification/v2.5.0.md b/pages/docs/reference/specification/v2.5.0.md deleted file mode 100644 index 5d45dfaf2bf5..000000000000 --- a/pages/docs/reference/specification/v2.5.0.md +++ /dev/null @@ -1,2543 +0,0 @@ -# AsyncAPI Specification - -#### Disclaimer - -Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). Mainly because **it's a great work** and we want to keep as much compatibility as possible with the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification). - -#### Version 2.5.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 and document message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). - -The AsyncAPI Specification defines a set of files required to describe such an API. -These files can then be used to create utilities, such as documentation, integration and/or testing tools. - -The file(s) MUST describe the operations an [application](#definitionsApplication) accepts. For instance, consider the following AsyncAPI definition snippet: - -```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignUp" -``` - -It means that the [application](#definitionsApplication) allows [consumers](#definitionsConsumer) to subscribe to the `user/signedup` [channel](#definitionsChannel) to receive userSignUp [messages](#definitionsMessage) produced by the application. - -**The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol. - - -## Definitions - -#### Server -A server MAY be a message broker that is capable of sending and/or receiving between a [producer](#definitionsProducer) and [consumer](#definitionsConsumer). 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 [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the [server](#definitionsServer) in order to connect and exchange [messages](#definitionsMessage). - -#### Producer -A producer is a type of application, connected to a [server](#definitionsServer), that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the [server](#definitionsServer), protocol, and use-case pattern. - -#### Consumer -A consumer is a type of application, connected to a [server](#definitionsServer) via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. - -#### Message -A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MUST 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). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume 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. - -#### 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. - -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) | **REQUIRED** The available channels and messages for the API. -components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. -tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. - - -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. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Info Object Example: - -```json -{ - "title": "AsyncAPI Sample App", - "description": "This is a sample server.", - "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" - }, - "version": "1.0.1" -} -``` - -```yaml -title: AsyncAPI Sample App -description: This is a sample server. -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 -version: 1.0.1 -``` - -#### Contact Object - -Contact information for the exposed API. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -name | `string` | The identifying name of the contact person/organization. -url | `string` | The URL pointing to the contact information. 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 -{ - "production": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" - } -} -``` - -```yaml -production: - url: development.gigantic-server.com - description: Development server - protocol: kafka - protocolVersion: '1.0.0' -``` - - -#### Server Object - -An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. -protocol | `string` | **REQUIRED**. The protocol this URL supports for connection. Supported protocol include, but are not limited to: `amqp`, `amqps`, `http`, `https`, `ibmmq`, `jms`, `kafka`, `kafka-secure`, `anypointmq`, `mqtt`, `secure-mqtt`, `solace`, `stomp`, `stomps`, `ws`, `wss`, `mercure`, `googlepubsub`. -protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. -description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -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 URL template. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. -tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers. -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. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Server Object Example - -A single server would be described as: - -```json -{ - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" -} -``` - -```yaml -url: development.gigantic-server.com -description: Development server -protocol: kafka -protocolVersion: '1.0.0' -``` - -The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): - -```json -{ - "servers": { - "development": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "tags": [ - { - "name": "env:development", - "description": "This environment is meant for developers to run their own tests" - } - ] - }, - "staging": { - "url": "staging.gigantic-server.com", - "description": "Staging server", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "tags": [ - { - "name": "env:staging", - "description": "This environment is a replica of the production environment" - } - ] - }, - "production": { - "url": "api.gigantic-server.com", - "description": "Production server", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "tags": [ - { - "name": "env:production", - "description": "This environment is the live environment available for final users" - } - ] - } - } -} -``` - -```yaml -servers: - development: - url: development.gigantic-server.com - description: Development server - protocol: amqp - protocolVersion: 0.9.1 - tags: - - name: "env:development" - description: "This environment is meant for developers to run their own tests" - staging: - url: staging.gigantic-server.com - description: Staging server - protocol: amqp - protocolVersion: 0.9.1 - tags: - - name: "env:staging" - description: "This environment is a replica of the production environment" - production: - url: api.gigantic-server.com - description: Production server - protocol: amqp - protocolVersion: 0.9.1 - tags: - - name: "env:production" - description: "This environment is the live environment available for final users" -``` - -The following shows how variables can be used for a server configuration: - -```json -{ - "servers": { - "production": { - "url": "{username}.gigantic-server.com:{port}/{basePath}", - "description": "The production API server", - "protocol": "secure-mqtt", - "variables": { - "username": { - "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" - }, - "port": { - "enum": [ - "8883", - "8884" - ], - "default": "8883" - }, - "basePath": { - "default": "v2" - } - } - } - } -} -``` - -```yaml -servers: - production: - url: '{username}.gigantic-server.com:{port}/{basePath}' - description: The production API server - protocol: secure-mqtt - variables: - username: - # note! no enum here means it is an open value - default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` - port: - enum: - - '8883' - - '8884' - default: '8883' - basePath: - # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` - default: v2 -``` - - -#### Server Variable Object - -An object representing a Server Variable for server URL template substitution. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. -default | `string` | The default value to use for substitution, and to send, if an alternate value is _not_ supplied. -description | `string` | An optional description for the server variable. [CommonMark syntax](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). - - - - - -#### 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 - -Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers. - -Channels are also known as "topics", "routing keys", "event types" or "paths". - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{channel} | [Channel Item Object](#channelItemObject) | A relative path to an individual channel. The field name MUST be in the form of a [RFC 6570 URI template](https://tools.ietf.org/html/rfc6570). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channelBindingsObject) to define them. - -##### Channels Object Example - -```json -{ - "user/signedup": { - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### Channel Item Object - -Describes the operations available on a single channel. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -$ref | `string` | Allows for a referenced definition of this channel item. The referenced structure MUST be in the form of a [Channel Item Object](#channelItemObject). In case a Channel Item Object field appears both in the defined object and the referenced object, the behavior is *undefined*. Resolution is done as defined by the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03).

**Deprecated:** Usage of the `$ref` property has been deprecated. -description | `string` | An optional description of this channel item. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). -subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation, which defines the messages produced by the application and sent to the channel. -publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation, which defines the messages consumed by the application from the channel. -parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)). -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 Item Object Example - -```json -{ - "description": "This channel is used to exchange messages about users signing up", - "subscribe": { - "summary": "A user signed up.", - "message": { - "description": "A longer description of the message", - "payload": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/user" - }, - "signup": { - "$ref": "#/components/schemas/signup" - } - } - } - } - }, - "bindings": { - "amqp": { - "is": "queue", - "queue": { - "exclusive": true - } - } - } -} -``` - -```yaml -description: This channel is used to exchange messages about users signing up -subscribe: - summary: A user signed up. - message: - description: A longer description of the message - payload: - type: object - properties: - user: - $ref: "#/components/schemas/user" - signup: - $ref: "#/components/schemas/signup" -bindings: - amqp: - is: queue - queue: - exclusive: true -``` - -Using `oneOf` to specify multiple messages per operation: - -```json -{ - "subscribe": { - "message": { - "oneOf": [ - { "$ref": "#/components/messages/signup" }, - { "$ref": "#/components/messages/login" } - ] - } - } -} -``` - -```yaml -subscribe: - message: - oneOf: - - $ref: '#/components/messages/signup' - - $ref: '#/components/messages/login' -``` - - -Using explicit by-name references to the servers on which the channel is available: - -```json -{ - "description": "This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments.", - "servers": [ - "rabbitmqBrokerInProd", - "rabbitmqBrokerInStaging", - ], - "subscribe": { - "message": { - "$ref": "#/components/messages/WebUICommand" - } - }, - "bindings": { - "amqp": { - "is": "queue" - } - } -} -``` - -```yaml -description: This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments. -servers: - - rabbitmqBrokerInProd - - rabbitmqBrokerInStaging -subscribe: - message: - $ref: "#/components/messages/WebUICommand" -bindings: - amqp: - is: queue -``` - - - - - -#### Operation Object - -Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. - -For example, an operation might describe a chat application use case where a user sends a text message to a group. A publish operation describes messages that are received by the chat application, whereas a subscribe operation describes messages that are sent by the chat application. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security 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) | 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 into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. -message | [Message Object](#messageObject) | [Reference Object](#referenceObject) | Map["oneOf", [[Message Object](#messageObject) | [Reference Object](#referenceObject)]] | A definition of the message that will be published or received by this operation. Map containing a single `oneOf` key is allowed here to specify multiple messages. However, **a message MUST be valid only against one of the message objects.** - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Operation Object Example - -```json -{ - "operationId": "registerUser", - "summary": "Action to sign a user up.", - "description": "A longer description", - "security": [ - { - "petstore_auth": [ - "write:pets", - "read:pets" - ] - } - ], - "tags": [ - { "name": "user" }, - { "name": "signup" }, - { "name": "register" } - ], - "message": { - "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" - } - } - } - }, - "bindings": { - "amqp": { - "ack": false - } - }, - "traits": [ - { "$ref": "#/components/operationTraits/kafka" } - ] -} -``` - -```yaml -operationId: registerUser -summary: Action to sign a user up. -description: A longer description -security: - - petstore_auth: - - write:pets - - read:pets -tags: - - name: user - - name: signup - - name: register -message: - 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" -bindings: - amqp: - ack: false -traits: - - $ref: "#/components/operationTraits/kafka" -``` - - - - -#### 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 `message` and `traits`. - -If you're looking to apply traits to a message, see the [Message Trait Object](#messageTraitObject). - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security 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) | 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 -``` - - - - -#### Parameters Object - -Describes a map of parameters included in a channel name. - -This map MUST contain all the parameters used in the parent channel name. - -##### Patterned Fields - -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 name. - -##### Parameters Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - } - } - }, - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - - -#### Parameter Object - -Describes a parameter included in a channel name. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -description | `string` | A verbose explanation of the parameter. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | Definition of the parameter. -location | `string` | A [runtime expression](#runtimeExpression) that specifies the location of the parameter value. Even when a definition for the target field exists, it MUST NOT be used to validate this parameter but, instead, the `schema` property MUST be used. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Parameter Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - }, - "location": "$message.payload#/user/id" - } - }, - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - location: $message.payload#/user/id - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### 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. - -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. - -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. - -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. - -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 ----|:---:|--- -messageId | `string` | Unique string used to identify the message. The id MUST be unique among all messages described in the API. The messageId value is **case-sensitive**. Tools and libraries MAY use the messageId to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. -headers | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -payload | `any` | Definition of the message payload. It can be of any type but defaults to [Schema object](#schemaObject). It must match the schema format, including encoding type - e.g Avro should be inlined as either a YAML or JSON object NOT a string to be parsed as YAML or JSON. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). When the payload is defined using a `$ref` to a remote file, it is RECOMMENDED the schema format includes the file encoding type to allow implementations to parse the file correctly. E.g., adding `+yaml` if content type is `application/vnd.apache.avro` results in `application/vnd.apache.avro+yaml`.

Check out the [supported schema formats table](#messageObjectSchemaFormatTable) 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](#messageObjectSchemaFormatTable). -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) | 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 into the message object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Message Object](#messageObject). - -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 2.5.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.5.0`, `application/vnd.aai.asyncapi+json;version=2.5.0`, `application/vnd.aai.asyncapi+yaml;version=2.5.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` | - - -##### Message Object Example - -```json -{ - "messageId": "userSignup", - "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 -messageId: userSignup -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 -{ - "messageId": "userSignup", - "name": "UserSignup", - "title": "User signup", - "summary": "Action to sign a user up.", - "description": "A longer description", - "tags": [ - { "name": "user" }, - { "name": "signup" }, - { "name": "register" } - ], - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "payload": { - "$ref": "path/to/user-create.avsc#/UserCreate" - } -} -``` - -```yaml -messageId: userSignup -name: UserSignup -title: User signup -summary: Action to sign a user up. -description: A longer description -tags: - - name: user - - name: signup - - name: register -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -payload: - $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 ----|:---:|--- -messageId | `string` | Unique string used to identify the message. The id MUST be unique among all messages described in the API. The messageId value is **case-sensitive**. Tools and libraries MAY use the messageId to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. -headers | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format/language used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). -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) | 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 -{ - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "contentType": "application/json" -} -``` - -```yaml -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -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 | `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. - -#### 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) | 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`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). - servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject). - serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). - channels | Map[`string`, [Channel Item Object](#channelItemObject)] | An object to hold reusable [Channel Item Objects](#channelItemObject). - 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). - 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). - 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" - } - } - } - }, - "servers": { - "development": { - "url": "{stage}.gigantic-server.com:{port}", - "description": "Development server", - "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 `gigantic-server.com`" - }, - "port": { - "enum": ["8883", "8884"], - "default": "8883" - } - }, - "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.", - "schema": { - "type": "string" - } - } - }, - "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 - servers: - development: - url: "{stage}.gigantic-server.com:{port}" - description: Development server - 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 `gigantic-server.com` - port: - enum: [8883, 8884] - default: 8883 - 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. - schema: - type: string - 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 -``` - -#### 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. - -##### 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 - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`. - -Alternatively, any time a Schema Object can be used, a [Reference Object](#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) | 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 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. - -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", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your 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. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### OAuth Flow Object Examples - -```JSON -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - }, - "authorizationCode": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```YAML -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your pets - authorizationCode: - authorizationUrl: https://example.com/api/oauth/dialog - tokenUrl: https://example.com/api/oauth/token - scopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - -#### Security Requirement Object - -Lists the required security schemes to execute this operation. -The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). - -When a list of Security Requirement Objects is defined on a [Server object](#serverObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the connection. - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names. Provide scopes that are required to establish successful connection with the server. If scopes are not needed, the list can be empty. For other security scheme types, the array MUST be empty. - -##### Security Requirement Object Examples - -###### User/Password Security Requirement - -```json -{ - "user_pass": [] -} -``` - -```yaml -user_pass: [] -``` - -###### API Key Security Requirement - -```json -{ - "api_key": [] -} -``` - -```yaml -api_key: [] -``` - -###### OAuth2 Security Requirement - -```json -{ - "petstore_auth": [ - "write:pets", - "read:pets" - ] -} -``` - -```yaml -petstore_auth: -- write:pets -- read:pets -``` - -### Correlation ID Object - -An object that specifies an identifier at design time that can used for message tracing and correlation. - -For specifying and computing the location of a Correlation ID, a [runtime expression](#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). - -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. - -### 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`](#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. diff --git a/pages/docs/reference/specification/v2.6.0.md b/pages/docs/reference/specification/v2.6.0.md deleted file mode 100644 index fb3651e6fd2e..000000000000 --- a/pages/docs/reference/specification/v2.6.0.md +++ /dev/null @@ -1,2547 +0,0 @@ -# AsyncAPI Specification - -#### Disclaimer - -Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). Mainly because **it's a great work** and we want to keep as much compatibility as possible with the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification). - -#### Version 2.6.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 and document message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc). - -The AsyncAPI Specification defines a set of files required to describe such an API. -These files can then be used to create utilities, such as documentation, integration and/or testing tools. - -The file(s) MUST describe the operations an [application](#definitionsApplication) accepts. For instance, consider the following AsyncAPI definition snippet: - -```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignUp" -``` - -It means that the [application](#definitionsApplication) allows [consumers](#definitionsConsumer) to subscribe to the `user/signedup` [channel](#definitionsChannel) to receive userSignUp [messages](#definitionsMessage) produced by the application. - -**The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol. - - -## Definitions - -#### Server -A server MAY be a message broker that is capable of sending and/or receiving between a [producer](#definitionsProducer) and [consumer](#definitionsConsumer). 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 [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the [server](#definitionsServer) in order to connect and exchange [messages](#definitionsMessage). - -#### Producer -A producer is a type of application, connected to a [server](#definitionsServer), that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the [server](#definitionsServer), protocol, and use-case pattern. - -#### Consumer -A consumer is a type of application, connected to a [server](#definitionsServer) via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. - -#### Message -A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MUST 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). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume 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. - -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) | **REQUIRED** The available channels and messages for the API. -components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. -tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique. -externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. - - -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. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Info Object Example: - -```json -{ - "title": "AsyncAPI Sample App", - "description": "This is a sample server.", - "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" - }, - "version": "1.0.1" -} -``` - -```yaml -title: AsyncAPI Sample App -description: This is a sample server. -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 -version: 1.0.1 -``` - -#### Contact Object - -Contact information for the exposed API. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -name | `string` | The identifying name of the contact person/organization. -url | `string` | The URL pointing to the contact information. 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 -{ - "production": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" - } -} -``` - -```yaml -production: - url: development.gigantic-server.com - description: Development server - protocol: kafka - protocolVersion: '1.0.0' -``` - - -#### Server Object - -An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. -protocol | `string` | **REQUIRED**. The protocol this URL supports for connection. Supported protocol include, but are not limited to: `amqp`, `amqps`, `http`, `https`, `ibmmq`, `jms`, `kafka`, `kafka-secure`, `anypointmq`, `mqtt`, `secure-mqtt`, `solace`, `stomp`, `stomps`, `ws`, `wss`, `mercure`, `googlepubsub`, `pulsar`. -protocolVersion | `string` | The version of the protocol used for connection. For instance: AMQP `0.9.1`, HTTP `2.0`, Kafka `1.0.0`, etc. -description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -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 URL template. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a connection or operation. -tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers. -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. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Server Object Example - -A single server would be described as: - -```json -{ - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "kafka", - "protocolVersion": "1.0.0" -} -``` - -```yaml -url: development.gigantic-server.com -description: Development server -protocol: kafka -protocolVersion: '1.0.0' -``` - -The following shows how multiple servers can be described, for example, at the AsyncAPI Object's [`servers`](#A2SServers): - -```json -{ - "servers": { - "development": { - "url": "development.gigantic-server.com", - "description": "Development server", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "tags": [ - { - "name": "env:development", - "description": "This environment is meant for developers to run their own tests" - } - ] - }, - "staging": { - "url": "staging.gigantic-server.com", - "description": "Staging server", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "tags": [ - { - "name": "env:staging", - "description": "This environment is a replica of the production environment" - } - ] - }, - "production": { - "url": "api.gigantic-server.com", - "description": "Production server", - "protocol": "amqp", - "protocolVersion": "0.9.1", - "tags": [ - { - "name": "env:production", - "description": "This environment is the live environment available for final users" - } - ] - } - } -} -``` - -```yaml -servers: - development: - url: development.gigantic-server.com - description: Development server - protocol: amqp - protocolVersion: 0.9.1 - tags: - - name: "env:development" - description: "This environment is meant for developers to run their own tests" - staging: - url: staging.gigantic-server.com - description: Staging server - protocol: amqp - protocolVersion: 0.9.1 - tags: - - name: "env:staging" - description: "This environment is a replica of the production environment" - production: - url: api.gigantic-server.com - description: Production server - protocol: amqp - protocolVersion: 0.9.1 - tags: - - name: "env:production" - description: "This environment is the live environment available for final users" -``` - -The following shows how variables can be used for a server configuration: - -```json -{ - "servers": { - "production": { - "url": "{username}.gigantic-server.com:{port}/{basePath}", - "description": "The production API server", - "protocol": "secure-mqtt", - "variables": { - "username": { - "default": "demo", - "description": "This value is assigned by the service provider, in this example `gigantic-server.com`" - }, - "port": { - "enum": [ - "8883", - "8884" - ], - "default": "8883" - }, - "basePath": { - "default": "v2" - } - } - } - } -} -``` - -```yaml -servers: - production: - url: '{username}.gigantic-server.com:{port}/{basePath}' - description: The production API server - protocol: secure-mqtt - variables: - username: - # note! no enum here means it is an open value - default: demo - description: This value is assigned by the service provider, in this example `gigantic-server.com` - port: - enum: - - '8883' - - '8884' - default: '8883' - basePath: - # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2` - default: v2 -``` - - -#### Server Variable Object - -An object representing a Server Variable for server URL template substitution. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. -default | `string` | The default value to use for substitution, and to send, if an alternate value is _not_ supplied. -description | `string` | An optional description for the server variable. [CommonMark syntax](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). - - - - - -#### 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 - -Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers. - -Channels are also known as "topics", "routing keys", "event types" or "paths". - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{channel} | [Channel Item Object](#channelItemObject) | A relative path to an individual channel. The field name MUST be in the form of a [RFC 6570 URI template](https://tools.ietf.org/html/rfc6570). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channelBindingsObject) to define them. - -##### Channels Object Example - -```json -{ - "user/signedup": { - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/signedup: - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### Channel Item Object - -Describes the operations available on a single channel. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -$ref | `string` | Allows for a referenced definition of this channel item. The referenced structure MUST be in the form of a [Channel Item Object](#channelItemObject). In case a Channel Item Object field appears both in the defined object and the referenced object, the behavior is *undefined*. Resolution is done as defined by the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03).

**Deprecated:** Usage of the `$ref` property has been deprecated. -description | `string` | An optional description of this channel item. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). -subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation, which defines the messages produced by the application and sent to the channel. -publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation, which defines the messages consumed by the application from the channel. -parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)). -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 Item Object Example - -```json -{ - "description": "This channel is used to exchange messages about users signing up", - "subscribe": { - "summary": "A user signed up.", - "message": { - "description": "A longer description of the message", - "payload": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/user" - }, - "signup": { - "$ref": "#/components/schemas/signup" - } - } - } - } - }, - "bindings": { - "amqp": { - "is": "queue", - "queue": { - "exclusive": true - } - } - } -} -``` - -```yaml -description: This channel is used to exchange messages about users signing up -subscribe: - summary: A user signed up. - message: - description: A longer description of the message - payload: - type: object - properties: - user: - $ref: "#/components/schemas/user" - signup: - $ref: "#/components/schemas/signup" -bindings: - amqp: - is: queue - queue: - exclusive: true -``` - -Using `oneOf` to specify multiple messages per operation: - -```json -{ - "subscribe": { - "message": { - "oneOf": [ - { "$ref": "#/components/messages/signup" }, - { "$ref": "#/components/messages/login" } - ] - } - } -} -``` - -```yaml -subscribe: - message: - oneOf: - - $ref: '#/components/messages/signup' - - $ref: '#/components/messages/login' -``` - - -Using explicit by-name references to the servers on which the channel is available: - -```json -{ - "description": "This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments.", - "servers": [ - "rabbitmqBrokerInProd", - "rabbitmqBrokerInStaging", - ], - "subscribe": { - "message": { - "$ref": "#/components/messages/WebUICommand" - } - }, - "bindings": { - "amqp": { - "is": "queue" - } - } -} -``` - -```yaml -description: This application publishes WebUICommand messages to an AMQP queue on RabbitMQ brokers in the Staging and Production environments. -servers: - - rabbitmqBrokerInProd - - rabbitmqBrokerInStaging -subscribe: - message: - $ref: "#/components/messages/WebUICommand" -bindings: - amqp: - is: queue -``` - - - - - -#### Operation Object - -Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. - -For example, an operation might describe a chat application use case where a user sends a text message to a group. A publish operation describes messages that are received by the chat application, whereas a subscribe operation describes messages that are sent by the chat application. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. -security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security 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) | 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 into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. -message | [Message Object](#messageObject) | [Reference Object](#referenceObject) | Map["oneOf", [[Message Object](#messageObject) | [Reference Object](#referenceObject)]] | A definition of the message that will be published or received by this operation. Map containing a single `oneOf` key is allowed here to specify multiple messages. However, **a message MUST be valid only against one of the message objects.** - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Operation Object Example - -```json -{ - "operationId": "registerUser", - "summary": "Action to sign a user up.", - "description": "A longer description", - "security": [ - { - "petstore_auth": [ - "write:pets", - "read:pets" - ] - } - ], - "tags": [ - { "name": "user" }, - { "name": "signup" }, - { "name": "register" } - ], - "message": { - "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" - } - } - } - }, - "bindings": { - "amqp": { - "ack": false - } - }, - "traits": [ - { "$ref": "#/components/operationTraits/kafka" } - ] -} -``` - -```yaml -operationId: registerUser -summary: Action to sign a user up. -description: A longer description -security: - - petstore_auth: - - write:pets - - read:pets -tags: - - name: user - - name: signup - - name: register -message: - 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" -bindings: - amqp: - ack: false -traits: - - $ref: "#/components/operationTraits/kafka" -``` - - - - -#### 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 `message` and `traits`. - -If you're looking to apply traits to a message, see the [Message Trait Object](#messageTraitObject). - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -summary | `string` | A short summary of what the operation is about. -description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security 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) | 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 -``` - - - - -#### Parameters Object - -Describes a map of parameters included in a channel name. - -This map MUST contain all the parameters used in the parent channel name. - -##### Patterned Fields - -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 name. - -##### Parameters Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - } - } - }, - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - - -#### Parameter Object - -Describes a parameter included in a channel name. - -##### Fixed Fields - -Field Name | Type | Description ----|:---:|--- -description | `string` | A verbose explanation of the parameter. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | Definition of the parameter. -location | `string` | A [runtime expression](#runtimeExpression) that specifies the location of the parameter value. Even when a definition for the target field exists, it MUST NOT be used to validate this parameter but, instead, the `schema` property MUST be used. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### Parameter Object Example - -```json -{ - "user/{userId}/signup": { - "parameters": { - "userId": { - "description": "Id of the user.", - "schema": { - "type": "string" - }, - "location": "$message.payload#/user/id" - } - }, - "subscribe": { - "message": { - "$ref": "#/components/messages/userSignedUp" - } - } - } -} -``` - -```yaml -user/{userId}/signup: - parameters: - userId: - description: Id of the user. - schema: - type: string - location: $message.payload#/user/id - subscribe: - message: - $ref: "#/components/messages/userSignedUp" -``` - - - - -#### 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 ----|:---:|--- -messageId | `string` | Unique string used to identify the message. The id MUST be unique among all messages described in the API. The messageId value is **case-sensitive**. Tools and libraries MAY use the messageId to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. -headers | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -payload | `any` | Definition of the message payload. It can be of any type but defaults to [Schema object](#schemaObject). It must match the schema format, including encoding type - e.g Avro should be inlined as either a YAML or JSON object NOT a string to be parsed as YAML or JSON. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). When the payload is defined using a `$ref` to a remote file, it is RECOMMENDED the schema format includes the file encoding type to allow implementations to parse the file correctly. E.g., adding `+yaml` if content type is `application/vnd.apache.avro` results in `application/vnd.apache.avro+yaml`.

Check out the [supported schema formats table](#messageObjectSchemaFormatTable) 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](#messageObjectSchemaFormatTable). -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) | 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 into the message object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Message Object](#messageObject). - -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 2.6.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.6.0`, `application/vnd.aai.asyncapi+json;version=2.6.0`, `application/vnd.aai.asyncapi+yaml;version=2.6.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` | - - -##### Message Object Example - -```json -{ - "messageId": "userSignup", - "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 -messageId: userSignup -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 -{ - "messageId": "userSignup", - "name": "UserSignup", - "title": "User signup", - "summary": "Action to sign a user up.", - "description": "A longer description", - "tags": [ - { "name": "user" }, - { "name": "signup" }, - { "name": "register" } - ], - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "payload": { - "$ref": "path/to/user-create.avsc#/UserCreate" - } -} -``` - -```yaml -messageId: userSignup -name: UserSignup -title: User signup -summary: Action to sign a user up. -description: A longer description -tags: - - name: user - - name: signup - - name: register -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -payload: - $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 ----|:---:|--- -messageId | `string` | Unique string used to identify the message. The id MUST be unique among all messages described in the API. The messageId value is **case-sensitive**. Tools and libraries MAY use the messageId to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. -headers | [Schema Object](#schemaObject) | [Reference Object](#referenceObject) | Schema definition of the application headers. Schema MUST be of type "object". It **MUST NOT** define the protocol headers. -correlationId | [Correlation ID Object](#correlationIdObject) | [Reference Object](#referenceObject) | Definition of the correlation ID used for message tracing or matching. -schemaFormat | `string` | A string containing the name of the schema format/language used to define the message payload. If omitted, implementations should parse the payload as a [Schema object](#schemaObject). -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) | 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 -{ - "schemaFormat": "application/vnd.apache.avro+json;version=1.9.0", - "contentType": "application/json" -} -``` - -```yaml -schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' -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 | `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. - -#### 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) | 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`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). - servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject). - serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). - channels | Map[`string`, [Channel Item Object](#channelItemObject)] | An object to hold reusable [Channel Item Objects](#channelItemObject). - 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). - 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). - 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" - } - } - } - }, - "servers": { - "development": { - "url": "{stage}.gigantic-server.com:{port}", - "description": "Development server", - "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 `gigantic-server.com`" - }, - "port": { - "enum": ["8883", "8884"], - "default": "8883" - } - }, - "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.", - "schema": { - "type": "string" - } - } - }, - "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 - servers: - development: - url: "{stage}.gigantic-server.com:{port}" - description: Development server - 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 `gigantic-server.com` - port: - enum: [8883, 8884] - default: 8883 - 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. - schema: - type: string - 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 -``` - -#### 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. - -##### 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 - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`. - -Alternatively, any time a Schema Object can be used, a [Reference Object](#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) | 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 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. - -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", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your 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. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. - -This object MAY be extended with [Specification Extensions](#specificationExtensions). - -##### OAuth Flow Object Examples - -```JSON -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - }, - "authorizationCode": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" - } - } - } -} -``` - -```YAML -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: - write:pets: modify pets in your account - read:pets: read your pets - authorizationCode: - authorizationUrl: https://example.com/api/oauth/dialog - tokenUrl: https://example.com/api/oauth/token - scopes: - write:pets: modify pets in your account - read:pets: read your pets -``` - -#### Security Requirement Object - -Lists the required security schemes to execute this operation. -The name used for each property MUST correspond to a security scheme declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). - -When a list of Security Requirement Objects is defined on a [Server object](#serverObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the connection. - -##### Patterned Fields - -Field Pattern | Type | Description ----|:---:|--- -{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names. Provide scopes that are required to establish successful connection with the server. If scopes are not needed, the list can be empty. For other security scheme types, the array MUST be empty. - -##### Security Requirement Object Examples - -###### User/Password Security Requirement - -```json -{ - "user_pass": [] -} -``` - -```yaml -user_pass: [] -``` - -###### API Key Security Requirement - -```json -{ - "api_key": [] -} -``` - -```yaml -api_key: [] -``` - -###### OAuth2 Security Requirement - -```json -{ - "petstore_auth": [ - "write:pets", - "read:pets" - ] -} -``` - -```yaml -petstore_auth: -- write:pets -- read:pets -``` - -### Correlation ID Object - -An object that specifies an identifier at design time that can used for message tracing and correlation. - -For specifying and computing the location of a Correlation ID, a [runtime expression](#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). - -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. - -### 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`](#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. diff --git a/pages/docs/reference/specification/v2.x.md b/pages/docs/reference/specification/v2.x.md new file mode 100644 index 000000000000..a84a94a84a3c --- /dev/null +++ b/pages/docs/reference/specification/v2.x.md @@ -0,0 +1 @@ +To read about previous versions of AsyncAPI specification go to: https://v2.asyncapi.com/docs/reference \ No newline at end of file diff --git a/pages/docs/reference/specification/v3.0.0-next-major-spec.12.md b/pages/docs/reference/specification/v3.0.0.md similarity index 100% rename from pages/docs/reference/specification/v3.0.0-next-major-spec.12.md rename to pages/docs/reference/specification/v3.0.0.md diff --git a/public/_redirects b/public/_redirects index 0946f4ed143f..36dab81d1c1b 100644 --- a/public/_redirects +++ b/public/_redirects @@ -19,31 +19,28 @@ https://www.asyncapi.io/* https://www.asyncapi.com/:splat 301! # Redirection will be handled automatically by Action. # LATEST-SPEC-REDIRECTION:START -/docs/reference/specification/latest /docs/reference/specification/v2.6.0 302! +/docs/reference/specification/latest /docs/reference/specification/v3.0.0 302! # LATEST-SPEC-REDIRECTION:END # SPEC-REDIRECTION:START -/docs/reference/specification/3.0.0-next-major-spec.12 /docs/reference/specification/v3.0.0-next-major-spec.12 302! -/docs/reference/specification/2.6.0 /docs/reference/specification/v2.6.0 302! -/docs/reference/specification/2.5.0 /docs/reference/specification/v2.5.0 302! -/docs/reference/specification/2.4.0 /docs/reference/specification/v2.4.0 302! -/docs/reference/specification/2.3.0 /docs/reference/specification/v2.3.0 302! -/docs/reference/specification/2.2.0 /docs/reference/specification/v2.2.0 302! -/docs/reference/specification/2.1.0 /docs/reference/specification/v2.1.0 302! -/docs/reference/specification/2.0.0 /docs/reference/specification/v2.0.0 302! +/docs/reference/specification/3.0.0 /docs/reference/specification/v3.0.0 302! # SPEC-REDIRECTION:END /docs/specifications/latest /docs/reference/specification/latest 302! -/docs/specifications/2.4.0 /docs/reference/specification/v2.4.0 302! -/docs/specifications/2.3.0 /docs/reference/specification/v2.3.0 302! -/docs/specifications/2.2.0 /docs/reference/specification/v2.2.0 302! -/docs/specifications/2.1.0 /docs/reference/specification/v2.1.0 302! -/docs/specifications/2.0.0 /docs/reference/specification/v2.0.0 302! -/docs/specifications/v2.4.0 /docs/reference/specification/v2.4.0 302! -/docs/specifications/v2.3.0 /docs/reference/specification/v2.3.0 302! -/docs/specifications/v2.2.0 /docs/reference/specification/v2.2.0 302! -/docs/specifications/v2.1.0 /docs/reference/specification/v2.1.0 302! -/docs/specifications/v2.0.0 /docs/reference/specification/v2.0.0 302! +/docs/specifications/2.6.0 https://v2.asyncapi.com/docs/reference/specification/v2.6.0 302! +/docs/specifications/2.5.0 https://v2.asyncapi.com/docs/reference/specification/v2.5.0 302! +/docs/specifications/2.4.0 https://v2.asyncapi.com/docs/reference/specification/v2.4.0 302! +/docs/specifications/2.3.0 https://v2.asyncapi.com/docs/reference/specification/v2.3.0 302! +/docs/specifications/2.2.0 https://v2.asyncapi.com/docs/reference/specification/v2.2.0 302! +/docs/specifications/2.1.0 https://v2.asyncapi.com/docs/reference/specification/v2.1.0 302! +/docs/specifications/2.0.0 https://v2.asyncapi.com/docs/reference/specification/v2.0.0 302! +/docs/specifications/v2.6.0 https://v2.asyncapi.com/docs/reference/specification/v2.6.0 302! +/docs/specifications/v2.5.0 https://v2.asyncapi.com/docs/reference/specification/v2.5.0 302! +/docs/specifications/v2.4.0 https://v2.asyncapi.com/docs/reference/specification/v2.4.0 302! +/docs/specifications/v2.3.0 https://v2.asyncapi.com/docs/reference/specification/v2.3.0 302! +/docs/specifications/v2.2.0 https://v2.asyncapi.com/docs/reference/specification/v2.2.0 302! +/docs/specifications/v2.1.0 https://v2.asyncapi.com/docs/reference/specification/v2.1.0 302! +/docs/specifications/v2.0.0 https://v2.asyncapi.com/docs/reference/specification/v2.0.0 302! /docs/specifications/1.0.0 https://github.com/asyncapi/asyncapi/blob/master/versions/1.0.0/asyncapi.md 302! /docs/specifications/1.1.0 https://github.com/asyncapi/asyncapi/blob/master/versions/1.1.0/asyncapi.md 302! diff --git a/public/img/posts/release-notes-3.0.0/cover.webp b/public/img/posts/release-notes-3.0.0/cover.webp new file mode 100644 index 000000000000..ea8241f7c0a6 Binary files /dev/null and b/public/img/posts/release-notes-3.0.0/cover.webp differ