From 5793f4c4d027bdcfdb25e53e811494af79204360 Mon Sep 17 00:00:00 2001 From: Afzal Ansari Date: Wed, 25 Oct 2023 21:22:19 +0530 Subject: [PATCH 01/19] refactor: update frontpage animation for v3 (#1975) --- components/DemoAnimation.js | 38 +++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/components/DemoAnimation.js b/components/DemoAnimation.js index 107e483c6b5..6e302c74d35 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
From addf5ff1b049180c38f2488738e33ec892d83583 Mon Sep 17 00:00:00 2001 From: Jonas Lagoni Date: Tue, 31 Oct 2023 00:57:11 +0100 Subject: [PATCH 02/19] chore: small changes to v3 release notes (#2007) --- pages/blog/release-notes-3.0.0.md | 18 ++++++++++++++---- .../img/posts/release-notes-3.0.0/cover.webp | Bin 0 -> 57610 bytes 2 files changed, 14 insertions(+), 4 deletions(-) create mode 100644 public/img/posts/release-notes-3.0.0/cover.webp diff --git a/pages/blog/release-notes-3.0.0.md b/pages/blog/release-notes-3.0.0.md index 60b891da03c..0c7380a3f13 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/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 0000000000000000000000000000000000000000..ea8241f7c0a63dfda3705c57d597a8a6c0bed115 GIT binary patch literal 57610 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

Jx3Q6qb#*RW|Q=0V6 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 z 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 Date: Thu, 2 Nov 2023 10:25:38 -1000 Subject: [PATCH 03/19] docs: add v3 migration guide (#2008) Co-authored-by: akshatnema %0ACo-authored-by: Alejandra Quetzalli --- components/Asyncapi3Comparison.js | 562 ++++++++++++++++++++++++ components/data/buckets.js | 14 +- components/icons/Migration.js | 15 + components/icons/Users.js | 18 +- components/navigation/learningItems.js | 2 + cypress/test/Asyncapi3Comparison.cy.js | 40 ++ pages/docs/community/_section.md | 4 +- pages/docs/migration/_section.md | 4 + pages/docs/migration/index.md | 15 + pages/docs/migration/migrating-to-v3.md | 395 +++++++++++++++++ 10 files changed, 1056 insertions(+), 13 deletions(-) create mode 100644 components/Asyncapi3Comparison.js create mode 100644 components/icons/Migration.js create mode 100644 cypress/test/Asyncapi3Comparison.cy.js create mode 100644 pages/docs/migration/_section.md create mode 100644 pages/docs/migration/index.md create mode 100644 pages/docs/migration/migrating-to-v3.md diff --git a/components/Asyncapi3Comparison.js b/components/Asyncapi3Comparison.js new file mode 100644 index 00000000000..c4e8800204b --- /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/data/buckets.js b/components/data/buckets.js index a171d271885..8ecab700fa1 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 00000000000..77180efeba8 --- /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 c46a89deb77..9f43fdcb633 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 65ba491f9a9..f04382b44ae 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 00000000000..15893bfd5f9 --- /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/docs/community/_section.md b/pages/docs/community/_section.md index 6874743a00f..1ef99a267b1 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 00000000000..48556fd333c --- /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 00000000000..195bcc35cf5 --- /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 00000000000..9d20b8bbefc --- /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 +... +``` From 067f86a2ffa97af2091320934557636a90dff804 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Wed, 8 Nov 2023 10:02:36 +0100 Subject: [PATCH 04/19] feat: cleanup reference docs for 3.0 (#2281) --- pages/docs/reference/specification/v2.0.0.md | 2205 -------------- pages/docs/reference/specification/v2.1.0.md | 2336 --------------- pages/docs/reference/specification/v2.2.0.md | 2432 ---------------- pages/docs/reference/specification/v2.3.0.md | 2453 ---------------- pages/docs/reference/specification/v2.4.0.md | 2510 ---------------- pages/docs/reference/specification/v2.5.0.md | 2543 ---------------- pages/docs/reference/specification/v2.6.0.md | 2547 ----------------- pages/docs/reference/specification/v2.x.md | 1 + ...v3.0.0-next-major-spec.12.md => v3.0.0.md} | 0 public/_redirects | 35 +- 10 files changed, 17 insertions(+), 17045 deletions(-) delete mode 100644 pages/docs/reference/specification/v2.0.0.md delete mode 100644 pages/docs/reference/specification/v2.1.0.md delete mode 100644 pages/docs/reference/specification/v2.2.0.md delete mode 100644 pages/docs/reference/specification/v2.3.0.md delete mode 100644 pages/docs/reference/specification/v2.4.0.md delete mode 100644 pages/docs/reference/specification/v2.5.0.md delete mode 100644 pages/docs/reference/specification/v2.6.0.md create mode 100644 pages/docs/reference/specification/v2.x.md rename pages/docs/reference/specification/{v3.0.0-next-major-spec.12.md => v3.0.0.md} (100%) 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 00f27112ab7..00000000000 --- 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 cba91b80933..00000000000 --- 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 84991230b60..00000000000 --- 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 ad5ee294b3e..00000000000 --- 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 b7426616013..00000000000 --- 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 5d45dfaf2bf..00000000000 --- 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 fb3651e6fd2..00000000000 --- 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 00000000000..a84a94a84a3 --- /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 0946f4ed143..36dab81d1c1 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! From d51fa0d3c6e452cfd5d6fde322b464eb668fabac Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Thu, 9 Nov 2023 19:18:58 +0100 Subject: [PATCH 05/19] chore: update instructions for some tools promotion usage (#2299) --- components/GeneratorInstallation.js | 14 ++++++++------ pages/tools/cli.js | 1 - pages/tools/github-actions.js | 4 ++-- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/components/GeneratorInstallation.js b/components/GeneratorInstallation.js index fec713d96c5..947715aa0a6 100644 --- a/components/GeneratorInstallation.js +++ b/components/GeneratorInstallation.js @@ -27,13 +27,13 @@ export default function GeneratorInstallation({ }) { } function getNpmCode() { - return `npm install -g @asyncapi/generator -ag ${specPath} ${template} ${params}` + return `npm install -g @asyncapi/cli +asyncapi generate fromTemplate ${specPath} ${template} ${params}` } function getDockerCode() { - return `docker run --rm -it -v \${PWD}/example:/app/example \\ -asyncapi/generator ${specPath} ${template} ${params}` + return `docker run --rm -it -v \${PWD}/example:/app/example -v \${PWD}/output:/app/output \\ +asyncapi/cli generate fromTemplate ${specPath} ${template} ${params}` } return ( @@ -56,10 +56,12 @@ asyncapi/generator ${specPath} ${template} ${params}` codeBlocks={[{ language: 'npm', code: getNpmCode(), - }, { + }, + { language: 'Docker', code: getDockerCode(), - }]} + }, + ]} />
) diff --git a/pages/tools/cli.js b/pages/tools/cli.js index 42b86598a80..19ff05fea3e 100644 --- a/pages/tools/cli.js +++ b/pages/tools/cli.js @@ -11,7 +11,6 @@ import { import CodeBlock from '../../components/editor/CodeBlock'; import Heading from '../../components/typography/Heading'; import Paragraph from '../../components/typography/Paragraph'; -import DocsButton from '../../components/buttons/DocsButton'; import Button from '../../components/buttons/Button'; const features = [ diff --git a/pages/tools/github-actions.js b/pages/tools/github-actions.js index e09304cdce3..c8292fe5693 100644 --- a/pages/tools/github-actions.js +++ b/pages/tools/github-actions.js @@ -78,10 +78,10 @@ jobs: uses: actions/checkout@v2 - name: Generating HTML from my AsyncAPI document - uses: asyncapi/github-action-for-generator@v0.2.0 + uses: asyncapi/github-action-for-generator - name: Deploy GH page - uses: JamesIves/github-pages-deploy-action@3.4.2 + uses: JamesIves/github-pages-deploy-action with: ACCESS_TOKEN: \${{ secrets.GITHUB_TOKEN }} BRANCH: gh-pages From 16f4e1f37643ddca7380b84a398617f4b2772408 Mon Sep 17 00:00:00 2001 From: Animesh Kumar Date: Sat, 11 Nov 2023 03:29:25 +0530 Subject: [PATCH 06/19] docs: re-add `Servers tutorial` and change code snippet (#2275) Co-authored-by: Alejandra Quetzalli --- .../docs/tutorials/getting-started/servers.md | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 pages/docs/tutorials/getting-started/servers.md diff --git a/pages/docs/tutorials/getting-started/servers.md b/pages/docs/tutorials/getting-started/servers.md new file mode 100644 index 00000000000..6bca604ebe6 --- /dev/null +++ b/pages/docs/tutorials/getting-started/servers.md @@ -0,0 +1,56 @@ +--- +title: "Servers" +date: 2019-04-03T10:56:52+01:00 +menu: + docs: + parent: 'getting-started' +weight: 110 +--- + +In the previous lesson, you learned how to create the definition of a simple [Hello World application](/docs/getting-started/hello-world). Let's take it from there. + +In this tutorial, you'll learn how to add `servers` to your AsyncAPI document. Adding and defining servers is useful because it specifies where and how to connect. The connection facilitates where to send and receive messages. + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +servers: + production: + host: broker.mycompany.com + protocol: amqp + description: This is "My Company" broker. +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + + +You've now added a new section called `servers` in your AsyncAPI document. + +You might have noticed that our example mentions `amqp`, a very common protocol that was popularized by RabbitMQ (among others). While our example uses `amqp`, you can use any protocol. The most common protocols used are `mqtt` (widely adopted by the Internet of Things and mobile apps), `kafka` (popular for its streaming solution), `ws` (WebSockets are frequently used in browsers), and `http` (used in HTTP streaming APIs). + + + +The `servers` section defines where your application should connect to start sending and receiving messages. + +1. If you are using a broker-centric architecture such as Kafka or RabbitMQ, specify the broker URL. +2. If you have the classic client-server model such as for REST APIs, then your `server` should be the URL of the server. + + + +## Conclusion + +Now you know where the `Hello world application` connects to, and you can start receiving `hello {name}` messages. + +In the next section, you'll learn how to add security requirements to your server. From 9de27955271bf6cffa2ed0e7d1351450a8188db0 Mon Sep 17 00:00:00 2001 From: Animesh Kumar Date: Sat, 11 Nov 2023 03:35:18 +0530 Subject: [PATCH 07/19] docs: re-add `message validation guide` and change code snippet (#2282) --- pages/docs/guides/message-validation.md | 111 ++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 pages/docs/guides/message-validation.md diff --git a/pages/docs/guides/message-validation.md b/pages/docs/guides/message-validation.md new file mode 100644 index 00000000000..29ea985b947 --- /dev/null +++ b/pages/docs/guides/message-validation.md @@ -0,0 +1,111 @@ +--- +title: Message validation +description: This guide explains different use cases for AsyncAPI message validation. +weight: 130 +--- + +## Introduction +This guide explains different concepts of validating messages in event-driven communication. You will also learn what role AsyncAPI documents play in validation. + +## Message validation +To understand message validation in event-driven communication, we must first understand the basic components involved. +- Producer: responsible for producing messages. +- Consumer: responsible for getting the producer's messages. +- Broker: acts as a bridge between the consumer and the producer because messages travel through the broker. + +Message validation can occur in different places in your system. This guide highlights three of those: +- Both producers and consumers can do validation internally during runtime. +- API Gateway can handle message validation. +- Validation of messages can be a native solution implemented by the Schema Registry. +Because consumers and producers cannot communicate directly, the AsyncAPI file dictates what should be included in the payload when a service produces a message. The AsyncAPI document also tells the consumer about the message's properties. +Let's further break down how validation works for all. + +### Runtime validation +Messages produced and consumed are both required for runtime message validation. The AsyncAPI document should include descriptions of payload schemas so that you can read them in your application and validate messages that are consumed and produced by the application. + +Before messages reach the consumer, runtime validation ensures that any errors are resolved and valid messages are sent to your application. + +An example implementation of message validation in runtime is the [asyncapi-validator](https://github.com/WaleedAshraf/asyncapi-validator) library that enables you to validate messages produced/consumed in your application against schemas provided in your AsyncAPI document. +Check out the [message validation in the runtime](https://www.asyncapi.com/docs/tutorials/message-validation) tutorial if you want to get your hands dirty with message validation. + +```mermaid +graph TD + subgraph Producer + G[Message produced] -->|Message| B{Is Message valid?} + B -->|No| A[Logs] + end + B -->|Yes| C[Broker] + C -->|Message| E{Is Message valid?} + subgraph Consumer + E -->|No| F[Logs] + E -->|Yes| H[Message consumed] + end +``` + +### Gateway validation +A gateway intercepts all incoming messages and routes them through the middleware and handler pipelines. The gateway sits between the producer and the broker. First, the messages are routed through the gateway, and then the gateway determines whether the message is valid. If the message is invalid, it displays an error and is not forwarded to the broker. + +An example implementation of message validation in a gateway is the [AsyncAPI gateway](https://github.com/asyncapi/event-gateway). It intercepts all incoming messages moving them into a pipeline of middlewares and handlers such as message validation. You can use a Kafka consumer/producer[(kcat)](https://github.com/edenhill/kcat), a broker, and a simple WebSocket to run the AsyncAPI gateway in your machine. +Check out an [AsyncAPI file demo with Studio](https://studio.asyncapi.com/?url=https://raw.githubusercontent.com/asyncapi/event-gateway/master/deployments/k8s/event-gateway-demo/event-gateway-demo.asyncapi.yaml) to learn more about how an AsyncAPI file can be used in gateway validation. + + +Currently, only the Kafka protocol is supported. + + +```mermaid +graph TD + PR[Producer]-- Message --- EG[AsyncAPI Event-Gateway] + EG -- Message --- EGV{Is Message valid?} + EGV -->|Yes| BR[Broker] + EGV --- |No| INV{Fail when invalid?} + INV -->|Yes| ERR[/Fail/] -- Produce request errored --> PR + INV -->|No| BR +``` +The AsyncAPI document is important because payload schemas are taken from it, and messages are validated against it in your application. +You can spin up the AsyncAPI gateway using an AsyncAPI file. All the messages are forwarded to a WebSocket endpoint; if the message/payload is invalid, it includes a validation error message. + +### Schema Registry validation +Producers and consumers do not communicate with each other directly; rather, information transfer happens via Kafka. At the same time, the consumer still needs to know the type of data the producer is sending. Imagine if the producer starts sending bad data to Kafka or if the data type of your data gets changed. We need a way to have a common data type that must be agreed upon. + +This is where Schema Registry comes into play. It is an application that runs outside your Kafka protocol and handles schema distribution to producers and consumers by storing a copy of the schema in its local cache and validating them in Kafka. + +```mermaid +sequenceDiagram +Producer ->> Schema Registry: Register/checks message schema +Schema Registry ->> Producer: Return registration result + +Producer ->> Kafka: Publish message +Kafka ->> Consumer: Recieves message +Consumer ->> Schema Registry: Validate message schema +Schema Registry ->> Consumer: Return validation result +``` + +With the Schema Registry in place, the producer first talks to the Schema Registry and checks if the schema of the message it wants to send is available before sending it to the broker. If it cannot locate the schema, it registers it in the Schema Registry. Then the producer sends a message to the broker prefixed with a unique schema ID. When the consumer processes this message, it will communicate with the Schema Registry using the schema ID obtained from the producer. If there is a schema mismatch, the Schema Registry will throw an error, informing the producer that it violates the schema agreement. + +AsyncAPI is not directly involved in validation based on the Schema Registry. The good thing is that you do not have to duplicate schemas in your AsyncAPI document stored in Schema Registry. You can reference schemas from Schema Registry in your AsyncAPI documents. +Here's an example of an AsyncAPI document where you can see both `schemaFormat` and `payload` referenced from the Schema Registry: +```yml +asyncapi: 3.0.0 +info: + title: Example with Avro + version: 0.1.0 + +channels: + example: + address: 'example' + messages: + avroMessage: + payload: + schemaFormat: 'application/vnd.apache.avro;version=1.9.0' + schema: + $ref: 'https://raw.githubusercontent.com/asyncapi/website/20a31a0396b41dd24b1bac877ab7ce3f58037c28/public/resources/casestudies/adeo/CostingRequestPayload.avsc' + +operations: + onMessage: + action: receive + channel: + $ref: '#/channels/example' +``` + +--- + From 5a1a85a8d40aa0d2d3e1089f4951c8ded7a7567c Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Fri, 10 Nov 2023 23:11:28 +0100 Subject: [PATCH 08/19] docs: re-add `Validate AsyncAPI documents` (#2303) Co-authored-by: Alejandra Quetzalli --- pages/docs/guides/validate.md | 102 ++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 pages/docs/guides/validate.md diff --git a/pages/docs/guides/validate.md b/pages/docs/guides/validate.md new file mode 100644 index 00000000000..a17ccf35bf7 --- /dev/null +++ b/pages/docs/guides/validate.md @@ -0,0 +1,102 @@ +--- +title: "Validate AsyncAPI documents" +description: In this guide, you'll learn multiple ways to validate AsyncAPI documents. +weight: 120 +--- + +## Introduction +In this guide, you'll learn multiple ways to validate AsyncAPI documents. + +## Validate AsyncAPI documents +Validating an AsyncAPI document can mean one of two things: +- Validation against the specification. +- Validation against the best practices or company governance rules also known as linting. + +### Validate against specification +Validating against the specification ensures that every content of the document is written in accordance with the AsyncAPI specification. Several tool options exist for validating against the specification: _AsyncAPI Studio_, _AsyncAPI CLI_, and _Parsers_. + +#### AsyncAPI Studio validation +[AsyncAPI Studio](https://studio.asyncapi.com/) provides a visual and easy way to validate your AsyncAPI documents against the specification. (It uses the [AsyncAPI JavaScript parser](https://github.com/asyncapi/parser-js) behind the scenes to perform syntax checks and validate documents.) + +Errors in your document are highlighted with a red underline, showing which lines are invalid. The `Diagnostics` section also provides feedback, allowing you to further troubleshoot with detailed error messages. When a document is invalid, it provides the following error: `Empty or invalid document please fix errors / define AsyncAPI document`. + +#### AsyncAPI CLI validation +The following [AsyncAPI CLI](https://github.com/asyncapi/cli#installation) command validates AsyncAPI documents in your local computer or in CI/CD automation: + + ``` + asyncapi validate asyncapi.yaml + ``` + + + +You can also open AsyncAPI Studio from the CLI by running the command `asyncapi start studio`. + + + +#### Parsers (code) validation +AsyncAPI provides official [JavaScript](https://github.com/asyncapi/parser-js) and [Go](https://github.com/asyncapi/parser-go) parsers for validating AsyncAPI documents. + + +Official parsers use JSON Schema created for AsyncAPI specification. JSON Schema is not enough to fully validate AsyncAPI documents. Learn more about custom JSON Schemas validation needs. Official JavaScript parser supports and validates these special needs. + +Take it into account if you're thinking about writing your own parser using official JSON Schema. + + +### Validation against best practices or company governance rules +Now let's discuss options for validating against best practices or company governance rules, also known as **linting**. When various teams use AsyncAPI, you want to ensure they follow the same rules and are consistent across the organization. It is not enough to validate AsyncAPI documents against official specification rules. + + + +Let's discuss an example. While the `summary` property is optional in an AsyncAPI document, you could choose to require it for your organization. You would then implement a solution that enables you to enforce internal rules on AsyncAPI documents' providers. + + + +One way to do this is to use the **Spectral** open-source tool. It enables you to define company-specific rules that you can use internally. + +To get started: +1. Install [Spectral](https://meta.stoplight.io/docs/spectral/b8391e051b7d8-installation). +2. Create a file named `.spectral.yaml` to begin writing your API description and document rules. + Example: + ```js + { + "rules": { + // add your own rules here + } + } + ``` + +3. Create and add your own custom ruleset: + ```js + { + "rules": { + "valid-document-version": { + "message": "Application title must start with upper case", + "severity": "error", + "given": "$.info", + "then": [ + { + "field": "title", + "function": "pattern", + "functionOptions": { + "match": "^[A-Z]" + } + } + ] + } + } + } + ``` + +4. After setting up Spectral and creating custom rules following steps 1 - 3, validate your AsyncAPI document using this Spectral CLI command: + + ``` + spectral lint asyncapi.yaml + ``` + +--- + +## Additional resources +- [AsyncAPI **Studio READme**](https://github.com/asyncapi/studio#readme) +- [AsyncAPI **CLI READme**](https://github.com/asyncapi/cli#readme) +- [AsyncAPI **JavaScript Parsers READme**](https://github.com/asyncapi/parser-js#readme) +- [AsyncAPI **Go Parsers READme**](https://github.com/asyncapi/parser-go#readme) From eafbc7a81f83674e46634252a108c792c42b150a Mon Sep 17 00:00:00 2001 From: Animesh Kumar Date: Sat, 11 Nov 2023 04:16:40 +0530 Subject: [PATCH 09/19] docs: re-add `studio document validation` and change code snippet (#2276) Co-authored-by: Alejandra Quetzalli %0ACo-authored-by: Lukasz Gornicki --- .../tutorials/studio-document-validation.md | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 pages/docs/tutorials/studio-document-validation.md diff --git a/pages/docs/tutorials/studio-document-validation.md b/pages/docs/tutorials/studio-document-validation.md new file mode 100644 index 00000000000..91ea2a26b08 --- /dev/null +++ b/pages/docs/tutorials/studio-document-validation.md @@ -0,0 +1,116 @@ +--- +title: "Validate AsyncAPI document with Studio" +description: In this tutorial, you'll learn how to validate AsyncAPI documents using the AsyncAPI Studio tool. +weight: 120 +--- + +## Introduction +In this tutorial, you'll learn how to validate AsyncAPI documents using the [AsyncAPI Studio tool](https://studio.asyncapi.com/). + +You will start with a broken AsyncAPI document and troubleshoot via console errors step-by-step until you end up with a valid AsyncAPI document. This process will illustrate identifying [`REQUIRED` properties in AsyncAPI documents](https://www.asyncapi.com/docs/reference/specification/latest#A2SObject). + +## Background context +An AsyncAPI document is a file that defines and annotates the different components of a specific Event-Driven API. The format of the file must be JSON or YAML. You can use this document to generate both documentation and code. + +The AsyncAPI Studio tool allows you to develop an AsyncAPI document, validate it, preview it, convert it to the latest version, and visualize event flows. + +Now let's experiment with an invalid file to see how errors are displayed and how to make that file valid again. + +## Copy invalid AsyncAPI document +Let's pretend you have an invalid AsyncAPI document. + +1. Open [Studio](https://studio.asyncapi.com/). + + + +You can also skip the step below by clicking on New File in Studio and opening the Invalid Example template in the tutorials section. + + + +2. Copy and paste the below invalid AsyncAPI document: + +```yaml +asyncapi: 3.0.0 +info: + title: Streetlights API + version: '1.0.0' + description: | + The Smartylighting Streetlights API allows you + to remotely manage the city lights. + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0' + +servers: + mosquitto: + url: test.mosquitto.org + protocol: mqtt + +channels: + lightMeasured: + address: 'light/measured' + messages: + lightMeasuredMessage: + name: LightMeasured + payload: + type: object + properties: + id: + type: integer + minimum: true + description: Id of the streetlight. + lumens: + type: integer + minimum: 0 + description: Light intensity measured in lumens. + sentAt: + type: string + format: date-time + description: Date and time when the message was sent. + +operations: + onLightMeasured: + action: 'receive' + summary: Inform about environmental lighting conditions for a particular streetlight. + channel: + $ref: '#/channels/lightMeasured' +``` + +## Troubleshoot Studio errors +Let's fix the errors one by one until you end up with a valid AsyncAPI document. + +1. You can see the error message on the screen: `Empty or invalid document. Please fix errors/define AsyncAPI document.` + +2. Open **DIAGNOSTICS**, you can see more information related to your errors. + +3. Fix the incorrect server information. Use `host` instead of `url` + +```yaml +servers: + mosquitto: + host: test.mosquitto.org + protocol: mqtt +``` + +Notice how description property is missing; that doesn't make the AsyncAPI document invalid, but it's always better to include. + + +4. Read the next error: `"minimum" property type must be number`. Fix the `minimum` by changing it to: `0`. + +```yaml + properties: + id: + type: integer + minimum: 0 +``` +5. Congratulations! You identified and fixed all the errors, and now have a valid AsyncAPI document. + +## Summary +In this tutorial, you learned how to validate an AsyncAPI document using the AsyncAPI Studio tool. You also learned to troubleshoot an invalid AsyncAPI document by following the error message directions in diagnostics. In doing so, you learned how to identify `REQUIRED` properties in all AsyncAPI documents. + +## Next steps +Now that you have completed this tutorial, go ahead to learn [generate AsyncAPI messages (events)](/docs/tutorials/generate-code) which you will be sending to your application. + +You may also enjoy reading our [AsyncAPI document validation guide](/docs/guides/validate). + +--- From 8b1023a54813c6477c03ea20d964764b28e6cd1b Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Sat, 11 Nov 2023 00:25:35 +0100 Subject: [PATCH 10/19] docs: re-add `Create AsyncAPI document` (#2304) Co-authored-by: Alejandra Quetzalli --- .../tutorials/create-asyncapi-document.md | 183 ++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 pages/docs/tutorials/create-asyncapi-document.md diff --git a/pages/docs/tutorials/create-asyncapi-document.md b/pages/docs/tutorials/create-asyncapi-document.md new file mode 100644 index 00000000000..f6addf842c8 --- /dev/null +++ b/pages/docs/tutorials/create-asyncapi-document.md @@ -0,0 +1,183 @@ +--- +title: Create AsyncAPI document +description: In this tutorial, you'll learn how to create an AsyncAPI document. +weight: 80 +--- + +## Introduction + +In this tutorial, you'll learn how to create an AsyncAPI document based on a sample real-world use case. Additionally, you will learn about event-driven architecture, message brokers, pub/sub pattern. + +Let's pretend you have a company called Smarty Lighting, and you install smart-city streetlight lighting systems. Such a smart lighting system is an Internet of Things (IoT) use case. You will create a Smarty Lighting Streetlights application using Node.js and Mosquitto (MQTT) as the message broker. Your application will allow you to manage city lights remotely. + +You want to build a system that can turn streetlights on and off based on their environmental conditions: + +- You will implement an event-driven architecture (EDA) with a message broker in its "center." + +- The Streetlights application will receive information about environmental lighting. + +- The Streetlights application will connect to the broker and receive a stream of events from all the streetlights devices reporting their conditions. + +- The Streetlights application is unaware of how many streetlights devices send measurement events to the broker; it just connects to the broker and receives all events. + + +## Background context + +Event-driven architecture (EDA) is a design pattern built around the production, detection, and reaction to events that take place in time. In this pattern, a message broker, event publishers, and subscribers are its main components for event exchange within microservices. + +[Message brokers](/docs/tutorials/getting-started/event-driven-architectures#message-broker) enables asynchronous communications between services so that the sending service need not wait for the receiving service’s reply. That allows interdependent services to “talk” with one another directly, even if they were written in different languages or implemented on different platforms. + +Furthermore, the [Pub/sub](/docs/tutorials/getting-started/event-driven-architectures#publishersubscriber) is appealing for IoT use cases due to two key features: support for flexible coupling between publishers/subscribers and inherent support for point-to-multipoint transmission. + +[MQTT](https://mqtt.org/), is a well-known protocol that is widely used in IoT applications because it was created particularly to address machine-to-machine (M2M) communication. + +## Create AsyncAPI document + +In this step, you will create an AsyncAPI document to describe the Streelights application. It will help you generate the code and the documentation later on. + +To create one, you can either use the [AsyncAPI Studio](https://studio.asyncapi.com) or the [AsyncAPI CLI](https://github.com/asyncapi/cli), depending on your project's needs. + + + +You can create a new `asyncapi.yaml` document by running: +`asyncapi new --example=tutorial.yml --no-tty`. + + + +Create the following specification document titled `asyncapi` with a `.yaml` extension. + + +{`asyncapi: 3.0.0 +info: + title: Streetlights App + version: '1.0.0' + description: | + The Smartylighting Streetlights application allows you + to remotely manage the city lights. + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0' +servers: + mosquitto: + host: test.mosquitto.org + protocol: mqtt +channels: + lightMeasured: + address: 'light/measured' + messages: + lightMeasuredMessage: + name: LightMeasured + payload: + type: object + properties: + id: + type: integer + minimum: 0 + description: Id of the streetlight. + lumens: + type: integer + minimum: 0 + description: Light intensity measured in lumens. + sentAt: + type: string + format: date-time + description: Date and time when the message was sent. +operations: + onLightMeasured: + action: 'receive' + summary: Information about environmental lighting conditions for a particular streetlight. + channel: + $ref: '#/channels/lightMeasured'`} + + +Let's break it down into pieces: + + +{`asyncapi: 3.0.0 +info: + title: Streetlights App + version: '1.0.0' + description: | + The Smartylighting Streetlights application allows you + to remotely manage the city lights. + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0'`} + + +- The `asyncapi` field indicates you use the AsyncAPI version 3.0.0. + +- The `info` field holds information about the Streetlights application. Here, the title, version, description, and license were defined. + +Moving on, let's talk about the `servers` section: + +{`servers: + mosquitto: + host: test.mosquitto.org + protocol: mqtt`} + + +In this section, you point to the Eclipse Mosquitto message broker. The `url` points to a real broker instance [hosted by the Mosquitto community](https://test.mosquitto.org/), and the `protocol` is MQTT. If you do not want to use the test instance, you can spin up your own broker locally with `docker run -it -p 1883:1883 eclipse-mosquitto:1.5`. Remember to change the `url` to `mqtt://localhost`. + +Now, let's move on to the `channels` section. In the `servers` section, you specified how to connect to the broker where the application sends messages to or receives messages from. In `channels`, you go into more details about the connection `address` inside the broker. (Example: A topic name that specifies what `messages` are available in the channel.) + + +{`channels: + lightMeasured: + address: 'light/measured' + messages: + lightMeasuredMessage: + name: LightMeasured + payload: + redacted for brevity`} + + +In this example, `light/measured` is the channel address. From the Streetlight application example perspective, it means that `light/measured` is the topic's name in the MQTT broker. + +Next is the `payload` property, which is used to understand how the event should look like when transfered over the specific channel: + + +{` payload: + type: object + properties: + id: + type: integer + minimum: 0 + description: Id of the streetlight. + lumens: + type: integer + minimum: 0 + description: Light intensity measured in lumens. + sentAt: + type: string + format: date-time + description: Date and time when the message was sent.`} + + +The `payload` property defines the event's content using AsyncAPI schemas. It means that your event payload should contain an `id` and a `lumens` property —which are integers bigger than zero—and a `sentAt` property which should be a string containing a date and time. + +> JSON Schema Draft 07 is 100% compatible with AsyncAPI schemas. You can also use other standards to describe payload schema, such as [Avro](https://github.com/asyncapi/avro-schema-parser#usage). + +The last section is `operations`, where you describe what the application described in the AsyncAPI document is doing. + + +{`operations: + onLightMeasured: + action: 'receive' + summary: Information about environmental lighting conditions for a particular streetlight. + channel: + $ref: '#/channels/lightMeasured'`} + + +You can see that the Streetlight application is a consumer that only receives events from the broker. Using the mandatory `channel` field, you specify with `$ref` what channel the events come from. + +The `onLightMeasured` key property describes the function or method name that takes care of this functionality in the generated code. It is a unique ID of the operation across the whole document. + +## Summary + +In this tutorial, you learned how to create an AsyncAPI specification document via a real-life example with an IoT use case. + +Your finished document is just a starting point; you must add your business logic. Take some time to play with it. There are still lots of things to be covered, but the intent of this tutorial is to make it simple for you to get an idea of the potential. + +## Next steps +Now that you've completed this tutorial, you can proceed to learn how to [validate your AsyncAPI document with AsyncAPI Studio](https://www.asyncapi.com/docs/tutorials/studio-document-validation). From 4b238aa668dcdcf348f0b03dc2920e69446c0b5e Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Sat, 11 Nov 2023 01:01:43 +0100 Subject: [PATCH 11/19] docs: re-add `Adding security` (#2305) Co-authored-by: Alejandra Quetzalli --- .../tutorials/getting-started/security.md | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 pages/docs/tutorials/getting-started/security.md diff --git a/pages/docs/tutorials/getting-started/security.md b/pages/docs/tutorials/getting-started/security.md new file mode 100644 index 00000000000..3c02ea281a7 --- /dev/null +++ b/pages/docs/tutorials/getting-started/security.md @@ -0,0 +1,147 @@ +--- +title: "Adding security" +weight: 150 +--- + +In production environments, your API may have to access a message broker that's protected by some auth mechanisms. + +Auth mechanism examples: +* User & password +* Certificates +* API keys +* OAuth 2 + +If you're using AsyncAPI to define an API that connects to a message broker, you'll probably use user/password or certificates. Traditionally, message brokers are infrastructure pieces that serve an internal purpose, and they're not exposed to the public. That's why their security mechanisms are also simpler than what we're used to with REST APIs. However, AsyncAPI also helps you define your HTTP streaming APIs, and therefore, it supports more sophisticated mechanisms like OAuth2 or OpenID. + +Continuing with the `hello world` application example, let's learn how to define a simple security scheme (mechanism) for it. + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +servers: + production: + host: broker.mycompany.com + protocol: amqp + description: This is "My Company" broker. + security: + - type: userPassword +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + $ref: '#/components/messages/hello-msg' + goodbye: + address: 'goodbye' + messages: + sayGoodbyeMessage: + $ref: '#/components/messages/goodbye-msg' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello' + receiveGoodbye: + action: 'receive' + channel: + $ref: '#/channels/goodbye' +components: + messages: + hello-msg: + payload: + type: object + properties: + name: + type: string + sentAt: + $ref: '#/components/schemas/sent-at' + goodbye-msg: + payload: + type: object + properties: + sentAt: + $ref: '#/components/schemas/sent-at' + schemas: + sent-at: + type: string + description: The date and time a message was sent. + format: datetime`} + + +The example above shows how to specify that your server (a Kafka broker) requires a user and a password to establish a connection. Let's break this down. + +There's a property in the server object called `security`. It's an array and can contain multiple security mechanisms. You chose to specify only one mechanism which is `userPassword`. + +A best practice is to put security details inside the `components.securitySchemes` section as it enables reusability across multiple servers. Below, you can see the same example, but this time, under server security, you see that `$ref` links to more security details located under the `user-password` object in `securitySchemes`. + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +servers: + production: + host: broker.mycompany.com + protocol: amqp + description: This is "My Company" broker. + security: + - $ref: "#/components/securitySchemes/user-password" +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + $ref: '#/components/messages/hello-msg' + goodbye: + address: 'goodbye' + messages: + sayGoodbyeMessage: + $ref: '#/components/messages/goodbye-msg' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello' + receiveGoodbye: + action: 'receive' + channel: + $ref: '#/channels/goodbye' +components: + messages: + hello-msg: + payload: + type: object + properties: + name: + type: string + sentAt: + $ref: '#/components/schemas/sent-at' + goodbye-msg: + payload: + type: object + properties: + sentAt: + $ref: '#/components/schemas/sent-at' + schemas: + sent-at: + type: string + description: The date and time a message was sent. + format: datetime + securitySchemes: + user-password: + type: userPassword`} + + + + +Learn more about the several kinds of security schemes. + + + +## Conclusion + +You can now define what security mechanisms your application needs to connect to the server. You've also seen how to require a user and a password, which is the most common use case. + +At this point, you know AsyncAPI well enough to create a simple `Hello world application`. However, real use cases are more complicated than that. The following tutorials can teach you how to create real-world use cases from zero to production. From c913ca4d7bbb99e51f6610e3ee81afddb5693aa2 Mon Sep 17 00:00:00 2001 From: Animesh Kumar Date: Sat, 11 Nov 2023 05:36:39 +0530 Subject: [PATCH 12/19] docs: re-add `AsyncAPI Documents` and change code snippet (#2274) Co-authored-by: Alejandra Quetzalli --- .../getting-started/asyncapi-documents.md | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 pages/docs/tutorials/getting-started/asyncapi-documents.md diff --git a/pages/docs/tutorials/getting-started/asyncapi-documents.md b/pages/docs/tutorials/getting-started/asyncapi-documents.md new file mode 100644 index 00000000000..6d11ace3144 --- /dev/null +++ b/pages/docs/tutorials/getting-started/asyncapi-documents.md @@ -0,0 +1,46 @@ +--- +title: "AsyncAPI documents" +date: 2019-04-01T10:56:52+01:00 +menu: + docs: + parent: 'getting-started' +weight: 101 +--- + +An AsyncAPI document is a file that defines and annotates the different components of **a specific Event-Driven API**. + +The file format must be JSON or YAML; however, only the subset of YAML that matches the JSON capabilities is allowed. + + +{`asyncapi: 3.0.0 +info: + title: Example application + version: '0.1.0' +channels: + userSignup: + address: 'user/signedup' + messages: + userSignedupMessage: + description: A message describing that a user just signed up. + payload: + type: object + additionalProperties: false + properties: + fullName: + type: string + email: + type: string + format: email + age: + type: integer + minimum: 18 +operations: + publishUserSignedup: + action: 'send' + channel: + $ref: '#/channels/userSignup'`} + + +The AsyncAPI document is a machine-readable definition of your Event-Driven API. That document can be used afterward to generate documentation and code, validate the messages that `Example application` sends, and even apply API management policies to your messages before they arrive at the broker. + +Your API documentation is now machine-readable (easily parseable by code) so the myriad of useful applications is endless. From 3b79c140771b10e2eadfdfc0c0e3928b4df3d656 Mon Sep 17 00:00:00 2001 From: Al Amin Muhammad <82694244+alaminthespecial@users.noreply.github.com> Date: Fri, 10 Nov 2023 19:18:48 -0500 Subject: [PATCH 13/19] docs: hello world tutorial for AsyncApi v3 (#2004) Co-authored-by: Alejandra Quetzalli %0ACo-authored-by: Lukasz Gornicki --- .../tutorials/getting-started/hello-world.md | 120 ++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 pages/docs/tutorials/getting-started/hello-world.md diff --git a/pages/docs/tutorials/getting-started/hello-world.md b/pages/docs/tutorials/getting-started/hello-world.md new file mode 100644 index 00000000000..654c809011f --- /dev/null +++ b/pages/docs/tutorials/getting-started/hello-world.md @@ -0,0 +1,120 @@ +--- +title: "Hello world" +weight: 30 +--- + +Let's define an application that's capable of receiving a `"hello {name}"` message: + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + + +Let's get into the details of this sample AsyncAPI document: + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + + +The first line of the specification starts with the document type `asyncapi` and the version (3.0.0). That line doesn't have to be the first one, but it's a best practice. + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + + +The `info` object contains the minimum required information about the application. It contains the `title`, which is a memorable name for the API, and the `version`. While it's not mandatory, it's strongly recommended to change the version whenever you make changes to the API. + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + + +The `channels` section of the specification houses all of the mediums where messages flow through. For example, some systems use `topic`, `event name` or `routing key`. Different kinds of information flow through each channel similar to the analogy of TV channels. + +You only have one channel called `hello`, and you see what message is available in this channel and how it must be structured. The `payload` object defines that the message must be a string and match the given regular expression in a string format such as `hello {name}`. + + +{`asyncapi: 3.0.0 +info: + title: Hello world application + version: '0.1.0' +channels: + hello: + address: 'hello' + messages: + sayHelloMessage: + payload: + type: string + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} + + +The `operations` section is where you describe what the application is doing. Each operation has a unique identifier for example, `receiveHello`. + +In the above example, you see that the `Hello world application` is a consumer listening to the `sayHelloMessage` message from the `hello` channel. In other words, you can say that the `Hello world application` subscribes to the `hello` topic to `receive` the `sayHelloMessage` message. That AsyncAPI document describes what the `Hello world application` is doing, not what others can do with it. From dfebdde35789a3292001677bf43c92021082783f Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Tue, 14 Nov 2023 18:35:13 +0100 Subject: [PATCH 14/19] docs: re-add `Coming from OpenAPI` (#2307) Co-authored-by: Alejandra Quetzalli --- components/Asyncapi3Comparison.js | 6 +- components/OpenAPIComparisonV3.js | 226 ++++++++++++++++++ .../getting-started/coming-from-openapi.md | 31 +++ 3 files changed, 260 insertions(+), 3 deletions(-) create mode 100644 components/OpenAPIComparisonV3.js create mode 100644 pages/docs/tutorials/getting-started/coming-from-openapi.md diff --git a/components/Asyncapi3Comparison.js b/components/Asyncapi3Comparison.js index c4e8800204b..e7c0773238a 100644 --- a/components/Asyncapi3Comparison.js +++ b/components/Asyncapi3Comparison.js @@ -120,7 +120,7 @@ export function Asyncapi3Comparison({ className = '' }) { Channels
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> - Channel Item + Channel
address @@ -229,7 +229,7 @@ export function Asyncapi3ChannelComparison({ className = '' }) { Channels
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> - Channel Item + Channel
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ Message: false })}> Messages @@ -303,7 +303,7 @@ export function Asyncapi3IdAndAddressComparison({ className = '' }) { Channels
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> - Channel Item + Channel
diff --git a/components/OpenAPIComparisonV3.js b/components/OpenAPIComparisonV3.js new file mode 100644 index 00000000000..911776bbc75 --- /dev/null +++ b/components/OpenAPIComparisonV3.js @@ -0,0 +1,226 @@ +import React, { useState } from 'react'; + +export default function OpenAPIComparisonV3({ className = '' }) { + const [hoverState, setHoverState] = useState({ + Info: false, + Servers: false, + Paths: false, + PathItem: true, + Summary: false, + Operations: false, + OperationItem: true, + OperationType: false, + Message: false, + Tags: false, + External: false, + Components: false + }); + + return ( +
+
+

OpenAPI 3.0

+ +
+
setHoverState(prevState => ({ ...prevState, Info: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Info: false })}> + Info +
+
+
setHoverState(prevState => ({ ...prevState, Servers: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Servers: false })}> + Servers +
+
+ Security +
+
+
setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Paths: false })}> + Paths +
+
{ return setHoverState(prevState => ({ ...prevState, PathItem: true })) }} onMouseLeave={() => { return setHoverState({ ...hoverState, PathItem: false }) }}> + Path Item + +
+
setHoverState(prevState => ({ ...prevState, Summary: true }))} onMouseLeave={() => { return setHoverState({ ...hoverState, Summary: false }) }}> + Summary and description +
+
+
setHoverState(prevState => ({ ...prevState, OperationItem: true }))} onMouseLeave={() => setHoverState({ ...hoverState, OperationItem: false })}> + Operation +
setHoverState(prevState => ({ ...prevState, OperationType: true }))} onMouseLeave={() => setHoverState({ ...hoverState, OperationType: false })}> + GET, PUT, POST, etc. +
+ +
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Message: false })}> + Request +
+
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Message: false })}> + Responses +
+ +
+
+
+
+
+
+
+
setHoverState(prevState => ({ ...prevState, Tags: true }))} onMouseLeave={() => setHoverState({ Tags: false })}> +

Tags

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

External Docs

+
+
+
setHoverState(prevState => ({ ...prevState, Components: true }))} onMouseLeave={() => setHoverState({ Components: false })}> + Components + +
+
+ Definitions +
+
+ Responses +
+
+ Parameters +
+
+ Response Headers +
+
+ Security Definitions +
+
+ Callbacks +
+
+ Links +
+
+
+
+
+ +
+

AsyncAPI 3.0

+ +
+
setHoverState(prevState => ({ ...prevState, Info: true }))} onMouseLeave={() => setHoverState({ Info: false })}> + Info +
+
+
setHoverState(prevState => ({ ...prevState, Servers: true }))} onMouseLeave={() => setHoverState({ Servers: false })}> + Servers (hosts + security) +
+
+
setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ Paths: false })}> + Channels + +
+
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> + Channel + +
+
+
setHoverState(prevState => ({ ...prevState, Summary: true }))} onMouseLeave={() => setHoverState({ Summary: false })} > + Summary, description +
+ + +
+
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ Message: false })}> + Messages + +
+ Headers +
+
+ Payload +
+
+
+ + +
+
+
+
+
+
setHoverState(prevState => ({ ...prevState, Operations: true }))} onMouseLeave={() => setHoverState({ Operations: false })}> + Operations +
+
setHoverState(prevState => ({ ...prevState, OperationItem: true }))} onMouseLeave={() => setHoverState({ OperationItem: false })}> + Operation + +
+
setHoverState(prevState => ({ ...prevState, OperationType: true }))} onMouseLeave={() => setHoverState({ OperationType: false })}> + action (send or receive) +
+
{ return setHoverState(prevState => ({ ...prevState, PathItem: true })) }} onMouseLeave={() => { return setHoverState({ ...hoverState, PathItem: false }) }}> + + Channel reference +
+
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Message: false })}> + Messages reference +
+
+
+
+
+
+
+ Id (application identifier) +
+
+
+
setHoverState(prevState => ({ ...prevState, Tags: true }))} onMouseLeave={() => setHoverState({ Tags: false })}> +

Tags

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

External Docs

+
+
+
setHoverState(prevState => ({ ...prevState, Components: true }))} onMouseLeave={() => setHoverState({ Components: false })}> + Components + +
+
+ Schemas +
+
+ Messages +
+
+ Security Schemes +
+
+ Parameters +
+
+ Correlation Ids +
+
+ Operation Traits +
+
+ Message Traits +
+
+ Server Bindings +
+
+ Channel Bindings +
+
+ Operation Bindings +
+
+ Message Bindings +
+
+
+
+
+
+ ) +} diff --git a/pages/docs/tutorials/getting-started/coming-from-openapi.md b/pages/docs/tutorials/getting-started/coming-from-openapi.md new file mode 100644 index 00000000000..ad7f6acb2cb --- /dev/null +++ b/pages/docs/tutorials/getting-started/coming-from-openapi.md @@ -0,0 +1,31 @@ +--- +title: "Coming from OpenAPI" +weight: 20 +--- + +If you're coming from OpenAPI, you must know that AsyncAPI [started as an adaptation of the OpenAPI specification](https://medium.com/asyncapi/whats-new-on-asyncapi-lots-2d9019a1869d). AsyncAPI wanted to be as compatible as possible with OpenAPI so that users could reuse parts in both. + +Before AsyncAPI `3.0.0`, you could find many similarities between OpenAPI and AsyncAPI. Remember that in the world of event-driven architectures, you have more than one protocol; therefore, some things are different. Check out the following comparison chart, inspired by [Darrel Miller's blog post](https://www.openapis.org/news/blogs/2016/10/tdc-structural-improvements-explaining-30-spec-part-2): + +import OpenAPIComparison from '../../../../components/OpenAPIComparison' + + + +To enable more flexibility, the AsyncAPI `3.0.0` specification changes more and is less similar to OpenAPI starting with this version. The biggest change is in the channel structure, where operations are separated from it. It is like detaching operations from paths in OpenAPI. + +import OpenAPIComparisonV3 from '../../../../components/OpenAPIComparisonV3' + + + +Aside from structural differences, you should know: + +1. AsyncAPI is compatible with OpenAPI schemas. +1. The message payload in AsyncAPI can be any value, not just an AsyncAPI/OpenAPI schema. For instance, it could be an Avro schema. +1. The [AsyncAPI server object](/docs/specifications/2.2.0/#serverObject) is almost identical to its OpenAPI counterpart, with the exception that `scheme` has been renamed to `protocol` and AsyncAPI introduces a new property called `protocolVersion`. AsyncAPI supports multiple protocols, not only HTTP, like in the case of OpenAPI. +1. OpenAPI path parameters and [AsyncAPI channel parameters](/docs/specifications/2.2.0/#parameterObject) are a bit different since AsyncAPI doesn't have the notion of "query" and "cookie", and header parameters can be defined in the [message object](/docs/specifications/2.2.0/#messageObject). Therefore, AsyncAPI channel parameters are the equivalent of OpenAPI path parameters. + +## Conclusion + +As you have seen above, OpenAPI and AsyncAPI are similar, but the specification's evolution will bring more differences in the future. In a real-world environment, systems don't have just REST APIs or events, but a mix of both. Most of the time, the information flowing in the events is very similar to the one the REST APIs have to handle in requests and responses; thus, being able to reuse schemas is a huge win. + +Let's learn how to create an AsyncAPI document that defines a "Hello world" application. From 5dcebb881dc913a280ac0b0c4668c0312a9c4687 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Thu, 16 Nov 2023 05:31:48 +0530 Subject: [PATCH 15/19] docs: adding `reply` info in a AsyncAPI document (#2228) Co-authored-by: Alejandra Quetzalli %0ACo-authored-by: Lukasz Gornicki --- .../concepts/asyncapi-document/_section.md | 4 + .../concepts/asyncapi-document/reply-info.md | 141 ++++++++++++++++++ 2 files changed, 145 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/_section.md create mode 100644 pages/docs/concepts/asyncapi-document/reply-info.md diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md new file mode 100644 index 00000000000..d7dea824ae2 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/_section.md @@ -0,0 +1,4 @@ +--- +title: 'AsyncAPI Document' +weight: 50 +--- \ No newline at end of file diff --git a/pages/docs/concepts/asyncapi-document/reply-info.md b/pages/docs/concepts/asyncapi-document/reply-info.md new file mode 100644 index 00000000000..db21c70b48c --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/reply-info.md @@ -0,0 +1,141 @@ +--- +title: Adding reply info +weight: 210 +--- + +Request/Reply is a communication pattern where one entity, the 'requestor,' sends a message to another, the 'replier', and waits for a response. Such a pattern is used when a component (or service) needs to initiate an action and receive a specific response in return, either synchronously or asynchronously. In Event-Driven Architectures, this communication pattern is asynchronous, meaning that the requester does not block and wait for an immediate response. Instead, it can continue processing other tasks or even send out other requests while waiting for the reply to arrive. + +In the case of multiple requests made, each request is processed independently and sends the reply/response to the corresponding requestor when ready. + +Here is diagram to illustrate the working of a basic request/reply pattern: +```mermaid +sequenceDiagram + Requester->>Channels: Send Request through Channel A + Channels->>Responder: Deliver Request + activate Responder + Responder-->>Channels: Send Reply through Channel B + deactivate Responder + Channels-->>Requester: Deliver Reply +``` + +The request/reply pattern in AsyncAPI works in the same fashion while supporting all the different sub-patterns. Irrespective of the sub-pattern you would like to represent, the request/reply pattern can be implemented in the AsyncAPI document in the `Operation` object. + +You can add the reply info using the `Operation Reply` object under the `Operation` object. The `reply` field represents the response details. + +In AsyncAPI, you have the flexibility to represent the request/reply pattern in two different ways. + +The first approach is when the requester specifies at runtime, within the request itself, where the response should be sent. Such an approach allows for the dynamic determination of the reply address based on factors such as the request message payload or header. + +The second approach is when the requester already knows exactly where the response should be sent. In such cases, the address of the reply channel is directly specified in the AsyncAPI document. + +## Dynamic response channel + +There are situations where you do not know the reply channel at the design time. Instead, the reply address is dynamically determined at runtime, based on factors such as the request message payload or header. + +In the case where you don't know the address of the reply yet, you have the option to either assign null to the `address` property or omit the property entirely indicating that the address is not known at the moment. The `address` property being referred to in this case is part of the channel that the operation with the reply references to. To dynamically specify where the reply should be sent, you can use the `Operation Reply Address` object. The `Operation Reply Address` object has a property called `location` that allows you to define a runtime expression that specifies the address of the reply channel. + +For instance, this pattern allows the replier to direct its response to a specific channel as defined by the requestor. This is typically achieved by including a `replyTo` property in the request header. The requestor specifies this property to indicate where it expects to receive the response, guiding the communication flow in a structured and predictable manner. + +```yml +asyncapi: 3.0.0 + +info: + title: Ping/pong example for a requester with a dynamic reply channel + version: 1.0.0 + description: Example with a requester that initiates a request/reply interaction, with the response directed to the destination specified in the request's `replyTo` header. + +channels: + ping: + address: /ping + messages: + ping: + $ref: '#/components/messages/ping' + pong: + address: null + messages: + pong: + $ref: '#/components/messages/pong' + +operations: + pingRequest: + action: send + channel: + $ref: '#/channels/ping' + reply: + address: + description: The response destination is dynamically set according to the `replyTo` field in the request header + location: "$message.header#/replyTo" + channel: + $ref: '#/channels/pong' +``` + +## Multiple channels with single message when reply address is known + +The request/reply pattern can also be implemented over multiple channels with a single message. You can do this by specifying multiple channels with a single message and specifying the same address for both the requester and the replier. + +Here's an example of setting up both the requestor and replier over the same address: +```yml +asyncapi: 3.0.0 + +info: + title: Ping/pong example with requester over the same channel + version: 1.0.0 + description: Requester example initiating a request-reply interaction, utilizing the same channel for both sending the request and receiving the reply. + +channels: + ping: + address: / + messages: + ping: + $ref: '#/components/messages/ping' + pong: + address: / + messages: + pong: + $ref: '#/components/messages/pong' + +operations: + pingRequest: + action: send + channel: + $ref: '#/channels/ping' + reply: + channel: + $ref: '#/channels/pong' +``` + +## Multiple messages over the same channel when reply address is known + +In some cases, representing the [same information](#multiple-channels-with-single-message) might require a different approach. You can do so by specifying multiple messages under the same channel. In such scenarios, use the `messages` property in the `Operation` object to explicitly define which message among the multiple messages available over the same channel is a request and which is a reply. + +Consider an example where multiple messages are transmitted over a single channel, all sharing the same address. In this setup, the `Operation` object is utilized to distinctly specify which of these messages serves as the request and which functions as the reply: +```yml +asyncapi: 3.0.0 + +info: + title: Ping/pong example when a channel contains multiple messages + version: 1.0.0 + description: Requester example that initiates the request-reply pattern within a root channel that contains multiple messages + +channels: + rootChannel: + address: / + messages: + ping: + $ref: '#/components/messages/ping' + pong: + $ref: '#/components/messages/pong' + +operations: + pingRequest: + action: send + channel: + $ref: '#/channels/rootChannel' + messages: + - $ref: "/components/messages/ping" + reply: + messages: + - $ref: "/components/messages/pong" + channel: + $ref: '#/channels/rootChannel' +``` From abf97221f1d4f01a289f282079ad15b0ae43bf3d Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Thu, 16 Nov 2023 06:03:29 +0530 Subject: [PATCH 16/19] docs: tutorial introducing request/reply (#2235) Co-authored-by: Alejandra Quetzalli %0ACo-authored-by: Lukasz Gornicki --- .../getting-started/request-reply.md | 141 ++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 pages/docs/tutorials/getting-started/request-reply.md diff --git a/pages/docs/tutorials/getting-started/request-reply.md b/pages/docs/tutorials/getting-started/request-reply.md new file mode 100644 index 00000000000..fcbdd0e6b0d --- /dev/null +++ b/pages/docs/tutorials/getting-started/request-reply.md @@ -0,0 +1,141 @@ +--- +title: Request/reply pattern +weight: 40 +--- + +In this tutorial, you'll learn how to implement the request/reply pattern in an AsyncAPI document using a straightforward pong-pong example. + +Before we begin, it would be beneficial for you to have a basic understanding of AsyncAPI and Event-Driven Architectures (EDA). If you need a refresher, refer to our [Event-Driven Architecture](/docs/tutorials/getting-started/event-driven-architectures) document. + +[Request/reply](https://www.enterpriseintegrationpatterns.com/patterns/messaging/RequestReply.html) is a messaging pattern involving two key components: the **requester**, which sends a request message, and the **replier**, responsible for receiving this request and responding with a reply. This pattern fundamentally revolves around these two roles, requester and replier. + +## Static reply address + +Here's how you can implement the request/reply pattern when the response address is known at the compile or design time. + +A requester can be configured with the `send` operation, where it dispatches a message to the `ping` channel and anticipates receiving a response through the `pong` channel. + +In the below example, the `Operation Reply` object within the `pingRequest` operation provides essential details, like the destination for the reply, which is the `pong` channel. Since the `pong` channel is configured with only one message, there's no need to explicitly define the reply message. Similarly, the `ping` channel has just one message, eliminating the need to specify the message sent in the request. + + +{`asyncapi: 3.0.0 +info: + title: Ping/pong example with static reply channel + version: 1.0.0 + description: Requester example that initiates the request/reply pattern on a different channel than the reply is using +channels: + ping: + address: /ping + messages: + ping: + $ref: '#/components/messages/ping' + pong: + address: /pong + messages: + pong: + $ref: '#/components/messages/pong' +operations: + pingRequest: + action: send + channel: + $ref: '#/channels/ping' + reply: + channel: + $ref: '#/channels/pong' +components: + messages: + ping: + payload: + type: object + properties: + event: + type: string + const: ping + pong: + payload: + type: object + properties: + event: + type: string + const: pong`} + + +## Dynamic reply address + +Occasionally, the destination for a reply cannot be predetermined during the design or compile phase. In such cases, the address for the reply is dynamically determined at runtime, allowing for more flexible and adaptive communication. + +In scenarios where the address or reply channel is unknown at design time, the `address` property can either be set to `null` or omitted entirely. To define the reply address dynamically, the `Operation Reply Address` object can be used, allowing for runtime expressions. That enables the `requester` to specify where the `replier` should send the reply, detailing the address's location and its specific position within the request. + +In this situation, the `location` property is assigned the runtime expression `$message.header#/replyTo`. Such an expression indicates that the address for the reply is located within the header of the request, specifically in the `replyTo` field. This method dynamically determines the reply address based on the content of the request header. + + +{`asyncapi: 3.0.0 +info: + title: Ping/pong example with reply specified as dynamic information provided in the runtime + version: 1.0.0 + description: Example document for an application that processes ping requests and replies to the address dynamically specified by the requestor in the message header +channels: + ping: + address: /ping + messages: + ping: + $ref: '#/components/messages/ping' + pong: + address: null + messages: + pong: + $ref: '#/components/messages/pong' +operations: + pingRequest: + action: receive + channel: + $ref: '#/channels/ping' + reply: + address: + description: Reply is sent to topic specified in 'replyTo' property in the message header + location: "$message.header#/replyTo" + channel: + $ref: '#/channels/pong' +components: + messages: + ping: + headers: + type: object + properties: + replyTo: + type: string + description: Provide path to which reply must be provided + requestId: + type: string + format: uuid + description: Provide request id that you will use to identify the reply match + payload: + type: object + properties: + event: + type: string + const: ping + correlationId: + $ref: "#/components/correlationIds/pingCorrelationId" + pong: + headers: + type: object + properties: + requestId: + type: string + format: uuid + description: Reply message must contain id of the request message + payload: + type: object + properties: + event: + type: string + const: pong + correlationId: + $ref: "#/components/correlationIds/pingCorrelationId" + correlationIds: + pingCorrelationId: + location: '$message.header#/requestId'`} + + +While the above examples are a simple implementation of the request/reply pattern, in a protocol-agnostic world there are many different ways to represent the request/reply pattern. All of which are supported by AsyncAPI. From ede5a28a3c4fee3614f3236802a372e3ab63665f Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Thu, 16 Nov 2023 07:00:22 +0530 Subject: [PATCH 17/19] docs: structure of a AsyncAPI document (#1922) Co-authored-by: Alejandra Quetzalli %0ACo-authored-by: Lukasz Gornicki --- .../concepts/asyncapi-document/structure.md | 581 ++++++++++++++++++ 1 file changed, 581 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/structure.md diff --git a/pages/docs/concepts/asyncapi-document/structure.md b/pages/docs/concepts/asyncapi-document/structure.md new file mode 100644 index 00000000000..6beb3d9b865 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/structure.md @@ -0,0 +1,581 @@ +--- +title: AsyncAPI document structure +weight: 60 +--- + +The structure of an AsyncAPI document is defined in a specific format and must follow the [AsyncAPI specification](/docs/reference/specification/latest). The structure of an AsyncAPI document has certain fields that you need to follow, although not all of them are mandatory. + +## Root elements + +Root elements of an AsyncAPI document provide an overview of the API's characteristics and behavior. These root elements collectively define the metadata, channels, components, and more of an AsyncAPI document. They provide a comprehensive overview of the API's characteristics and behavior. + +```mermaid +graph +A[asyncapi] +B[info] +C[servers] +D[channels] +E[operations] +F[components] + +A --> B +A --> C +A --> D +A --> E +A --> F +``` + +### `info` field + +The `info` field in an API document offers crucial metadata, including the API's title, version, description, contact details, and license. This field provides a comprehensive overview of the API, aiding developers, architects, and other stakeholders in quickly grasping its purpose and capabilities. As a mandatory element of the AsyncAPI specification, the `info` field often serves as the initial reference point for users navigating the API documentation. + +The `info` field encompasses various fields such as: + +- `title`: API title. +- `version`: API version. +- `description`: Brief description describing the API's purpose and features. +- `termsOfService`: URL or document specifying the API's terms of service. +- `contact`: Contact information of the API's owner or maintainer (name, email, and URL). +- `license`: API's license information, including name and URL. +- `tags`: Tags for categorizing and organizing API documentation. Also used for grouping applications logically. +- `externalDocs`: Links to additional, external documentation related to the API. + +Here's a visual representation of the `info` field and its properties: +```mermaid +graph LR + B(info) + C(title) + D(version) + E(description) + F(termsOfService) + G(contact) + J(license) + M(tags) + P(externalDocs) + + B --> C + B --> D + B --> E + B --> F + B --> G + B --> J + B --> M + B --> P +``` + +Below is an example of the `info` field: +```yaml +info: + title: My Event-Driven API + version: 1.0.0 + description: This API provides real-time event streaming capabilities. + termsOfService: https://example.com/terms-of-service + contact: + name: Rohit + email: rohitwashere@asyncapi.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + tags: + - name: Events + description: APIs related to event streaming + - name: Authentication + description: APIs for authentication and authorization + externalDocs: + description: Additional documentation + url: https://example.com/docs +``` + +### `servers` field + +The `servers` field allows you to detail a range of servers, outlining the network endpoints or message brokers to which applications can connect. That field includes vital connection information like protocol, host, port, and other options, facilitating connectivity across various environments such as production, staging, or development. + +Some of the fields of individual `servers` field are: + +- `host`: The server host name. It may include the port. +- `protocol`: The protocol or messaging protocol used by the server (e.g., AMQP, MQTT, WebSocket). +- `protocolVersion`: The version of the protocol used for the connection. +- `pathname`: The path to a resource in the host. +- `description`: An optional string describing the server. +- `title`: A human-friendly title for the server. +- `summary`: A summary of the server. +- `security`: A declaration of which security schemes can be used with this server. +- `tags`: A list of tags for logical grouping and categorization of servers. +- `externalDocs`: Additional external documentation for this server. +- `bindings`: A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server. + +Here's a visual representation of the `server` object and its properties: +```mermaid +graph LR + A[server] + B(host) + C(pathname) + D(protocol) + E(protocolVersion) + F(description) + G(title) + H(summary) + I(variables) + J(security) + K(tags) + L(externalDocs) + M(bindings) + + A --> B + A --> C + A --> D + A --> E + A --> F + A --> G + A --> H + A --> I + A --> J + A --> K + A --> L + A --> M +``` + +Below is an example of the `servers` field with multiple servers: +```yaml +servers: + production: + host: rabbitmq.in.mycompany.com:5672 + pathname: /v1 + protocol: amqp + protocolVersion: "1.0" + description: Production RabbitMQ broker (uses the `production` vhost). + title: Production Server + summary: Production environment server + security: + - type: http + scheme: bearer + tags: + - name: production + description: Production environment + externalDocs: + description: Additional documentation for the production server + url: https://example.com/docs/production + bindings: + amqp: + exchange: my-exchange + queue: my-queue + staging: + host: rabbitmq.in.mycompany.com:5672 + pathname: /v1 + protocol: amqp + protocolVersion: "1.0" + description: Staging RabbitMQ broker (uses the `staging` vhost). + title: Staging Server + summary: Staging environment server + security: + - type: apiKey + in: user + description: Provide your API key as the user and leave the password empty. + tags: + - name: staging + description: Staging environment + externalDocs: + description: Additional documentation for the staging server + url: https://example.com/docs/staging + bindings: + amqp: + exchange: my-exchange + queue: my-queue +``` + +### `channels` field + +With the `channels` field, you can provide a map of different channels the application communicates with during runtime. The `channels` represent the communication pathways through which messages are exchanged. You can specify their purpose, address, and the expected message formats for communication. Consumers of the specific API can understand the supported message-based interactions and the corresponding data models. + +Key components within the `channels` field include: + +- `address`: A string representation of this channel's address. +- `messages`: A map of the messages that will be sent to this channel by any application at any time. +- `title`: A human-readable title for the channel. +- `summary`: A short yet brief summary of the channel. +- `description`: A description of the channel, providing additional context and details of the message. +- `servers`: An array of `$ref` pointers to the definition of the servers in which this channel is available. If servers are absent or empty, this channel must be available on all the servers defined in the `servers` field. +- `parameters`: A map of the parameters included in the channel address. +- `tags`: A list of tags for logical grouping of channels. +- `externalDocs`: Additional external documentation for this channel. +- `bindings`: A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. + +Here's a visual representation of the `channels` field and its properties: +```mermaid +graph LR + A[channel] + B(address) + C(title) + D(description) + E(messages) + H(parameters) + J(servers) + M(bindings) + P(tags) + R(externalDocs) + + A -->B + A --> C + A --> D + A --> E + A --> H + A --> J + A --> M + A --> P + A --> R +``` + +Below is an example of of the `channels` field with one channel: +```yaml +channels: + user: + address: 'users.{userId}' + title: Users channel + description: This channel is used to exchange messages about user events. + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' + userCompletedOrder: + $ref: '#/components/messages/userCompletedOrder' + parameters: + userId: + $ref: '#/components/parameters/userId' + servers: + - $ref: '#/servers/production' + bindings: + amqp: + is: queue + queue: + exclusive: true + tags: + - name: user + description: User-related messages + externalDocs: + description: 'Find more info here' + url: 'https://example.com' +``` + +### `operations` field + +The `operations` field is used to comprehensively outline the various operations performed by the application. It offers a clear, structured description, detailing whether the application sends or receives messages and the specific purpose of each operation. + +Key components within the `operations` field include: + +- `action`: Use `send` type when it's expected that the application will send a message to the given channel, and `receive` type when the application should expect to receive messages from the given channel. +- `channel`: A `$ref` pointer to the definition of the channel in which this operation is performed. +- `title`: A human-friendly title for the operation. +- `summary`: A short summary of what the operation is about. +- `description`: A verbose explanation of the operation. +- `security`: A declaration of which security schemes are associated with this operation. +- `tags`: A list of tags for logical grouping and categorization of operations. +- `externalDocs`: Additional external documentation for this operation. +- `bindings` A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. +- `traits`: A list of traits to apply to the operation object. +- `messages`: A list of $ref pointers pointing to the supported Message Objects that can be processed by this operation. +- `reply`: The definition of the reply in a reply/request operation. + +Here's a visual representation of the `operations` field and its properties: +```mermaid +graph LR + A[operation] + B(title) + C(summary) + D(description) + E(channel) + F(action) + G(security) + H(tags) + I(bindings) + J(traits) + K(messages) + L(reply) + M(address) + N(channel) + + A --> B + A --> C + A --> D + A --> E + A --> F + A --> G + A --> H + A --> I + A --> J + A --> K + A --> L + L --> M + L --> N +``` + +Below is an example of of the `operations` field with one operation: +```yaml +operations: + sendUserSignUp: + action: send + title: User sign up + summary: Action to sign a user up. + description: A longer description + channel: + $ref: '#/channels/user' + security: + - type: oauth2 + description: The oauth security descriptions + flows: + clientCredentials: + tokenUrl: 'https://example.com/api/oauth/dialog' + availableScopes: + 'subscribe:auth_revocations': Scope required for authorization revocation topic + scopes: + - 'subscribe:auth_revocations' + tags: + - name: user + - name: signup + - name: register + bindings: + amqp: + ack: false + traits: + - $ref: "#/components/operationTraits/kafka" + messages: + - $ref: '#/components/messages/userSignedUp' + reply: + address: + location: '$message.header#/replyTo' + channel: + $ref: '#/channels/userSignupReply' + messages: + - $ref: '#/channels/userSignupReply/messages/userSignedUpReply' +``` + +### `components` field + +The `components` field allows for the definition of reusable structures or definitions applicable across various sections of your document. Items detailed within `components` only become part of the API when explicitly referenced by properties external to this field. Utilize it to avoid repetition and enhance the document's maintainability. + +Key components of the `channels` field include: + +- `schemas`: An object to hold the reusable [Schema Object](/docs/reference/specification/latest#schemaObject). +- `servers`: An object to hold the reusable [Server Objects](/docs/reference/specification/latest#serverObject). +- `channels`: An object to hold the reusable [Channel Objects](/docs/reference/specification/latest#channelObject). +- `operations`: An object to hold the reusable [Operation Item Objects](/docs/reference/specification/latest#operationObject). +- `messages`: An object to hold the reusable [Messages Objects](/docs/reference/specification/latest#messageObject). +- `securitySchemes`: An object to hold the reusable [Security Scheme Objects](/docs/reference/specification/latest#securitySchemeObject). +- `serverVariables`: An object to hold the reusable [Server Variable Objects](/docs/reference/specification/latest#serverVariableObject). +- `parameters`: Contains reusable [Parameter Objects](/docs/reference/specification/latest#parameterObject) that can be used in various parts of the AsyncAPI document. +- `correlationIds`: An object to hold the reusable [Correlation ID Objects](/docs/reference/specification/latest#correlationIdObject). +- `replies`: An object to hold the reusable [Operation Reply Objects](/docs/reference/specification/latest#operationReplyObject). +- `replyAddresses`: An object to hold the reusable [Operation Reply Address Objects](/docs/reference/specification/latest#operationReplyAddressObject). +- `externalDocs`: An object to hold the reusable [External Documentation Objects](docs/reference/specification/latest#externalDocumentationObject). +- `tags`: An object to hold the reusable [Tag Objects](/docs/reference/specification/latest#tagObject). +- `operationTraits`: An object to hold the reusable [Operation Trait Objects](/docs/reference/specification/latest#operationTraitObject). +- `messageTraits`: Represents common traits or characteristics that can be applied to messages or hold reusable [Message Trait Objects](/docs/reference/specification/latest#messageTraitObject). +- `serverBindings`: An object to hold the reusable [Server Bindings Objects](/docs/reference/specification/latest#serverBindingsObject). +- `channelBindings`: An object to hold the reusable [Channel Bindings Objects](/docs/reference/specification/latest#channelBindingsObject). +- `operationBindings`: An object to hold the reusable [Operation Bindings Objects](/docs/reference/specification/latest#operationBindingsObject). +- `messageBindings`: An object to hold the reusable [Message Bindings Objects](/docs/reference/specification/latest#messageBindingsObject). + +Here's a visual representation of the `components` field and its properties: +```mermaid +graph LR + A[components] + B(schemas) + C(messages) + D(serverVariables) + E(replies) + F(replyAddresses) + G(servers) + H(operations) + I(securitySchemes) + J(tags) + K(operationTraits) + L(channels) + M(serverBindings) + N(channelBindings) + O(operationBindings) + R(messageBindings) + P(externalDocs) + U(parameters) + W(correlationIds) + Y(messageTraits) + + A --> B + A --> C + A --> H + A --> G + A --> D + A --> L + A --> U + A --> P + A --> I + A --> W + A --> Y + A --> K + A --> J + A --> E + A --> F + A --> M + A --> N + A --> O + A --> R +``` + +Here's a code example of the components object in an AsyncAPI document: +```yaml +components: + + schemas: + Category: + type: object + properties: + id: + type: integer + format: int64 + AvroExample: + schemaFormat: application/vnd.apache.avro+json;version=1.9.0 + schema: + $ref: 'path/to/user-create.avsc/#UserCreate' + + servers: + development: + host: '{stage}.in.mycompany.com' + protocol: amqp + description: RabbitMQ broker + bindings: + $ref: '#/components/serverBindings/devAmqp' + variables: + stage: + $ref: '#/components/serverVariables/stage' + security: + - $ref: '#/components/securitySchemes/oauth' + + serverVariables: + stage: + default: demo + description: This value is assigned by the service provider in this example of `mycompany.com` + + channels: + user: + address: 'users.{userId}' + title: Users channel + description: This channel is used to exchange messages about user events. + messages: + userSignedUp: + $ref: '#/components/messages/userSignUp' + parameters: + userId: + $ref: '#/components/parameters/userId' + servers: + - $ref: '#/components/servers/development' + bindings: + $ref: '#/components/channelBindings/user' + tags: + - $ref: '#/components/tags/user' + externalDocs: + $ref: '#/components/externalDocs/infoDocs' + + messages: + userSignUp: + summary: Action to sign a user up. + traits: + - $ref: '#/components/messageTraits/commonHeaders' + payload: + $ref: '#/components/schemas/Category' + correlationId: + $ref: '#/components/correlationIds/default' + bindings: + $ref: '#/components/messageBindings/user' + + parameters: + userId: + description: Id of the user. + + correlationIds: + default: + description: Default Correlation ID + location: $message.header#/correlationId + + operations: + sendUserSignUp: + action: send + title: User sign up + bindings: + $ref: '#/components/operationBindings/sendUser' + traits: + - $ref: '#/components/operationTraits/binding' + reply: + $ref: '#/components/replies/signupReply' + + replies: + signupReply: + address: + $ref: '#/components/replyAddresses/signupReply' + channel: + $ref: '#/channels/userSignupReply' + + replyAddresses: + signupReply: + location: '$message.header#/replyTo' + + + securitySchemes: + oauth: + type: oauth2 + description: The oauth security descriptions + flows: + clientCredentials: + tokenUrl: 'https://example.com/api/oauth/dialog' + availableScopes: + 'subscribe:auth_revocations': Scope required for authorization revocation topic + scopes: + - 'subscribe:auth_revocations' + + operationTraits: + binding: + bindings: + amqp: + ack: false + + messageTraits: + commonHeaders: + headers: + type: object + properties: + my-app-header: + type: integer + minimum: 0 + maximum: 100 + + tags: + user: + name: user + description: User-related messages + + externalDocs: + infoDocs: + url: https://example.com/docs + description: 'Find more info here' + + serverBindings: + devAmqp: + amqp: + exchange: my-exchange + queue: my-queue + + channelBindings: + user: + amqp: + is: queue + queue: + exclusive: true + + operationBindings: + sendUser: + amqp: + ack: false + + messageBindings: + user: + amqp: + contentEncoding: gzip + messageType: 'user.signup' + bindingVersion: '0.2.0' +``` From 65f4959aa40b4ff6615bdbe54fff5516a2b85ffc Mon Sep 17 00:00:00 2001 From: Mahfuza Humayra Mohona Date: Thu, 16 Nov 2023 09:20:12 +0600 Subject: [PATCH 18/19] docs: add document for adding binding page (#2042) Co-authored-by: Alejandra Quetzalli %0ACo-authored-by: Lukasz Gornicki --- .../asyncapi-document/adding-bindings.md | 158 ++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/adding-bindings.md diff --git a/pages/docs/concepts/asyncapi-document/adding-bindings.md b/pages/docs/concepts/asyncapi-document/adding-bindings.md new file mode 100644 index 00000000000..6d6cf0c0f5c --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/adding-bindings.md @@ -0,0 +1,158 @@ +--- +title: Adding Bindings +weight: 260 +--- + +Bindings in AsyncAPI provide a way to add protocol-specific information to the AsyncAPI documentation. They can be added to different document parts, such as servers, channels, or messages; they specify standard details specific to a particular protocol. The purpose of bindings is to enhance the API's understanding and usage by providing additional context and configuration options for different protocols. + +The following diagram highlights the sections where bindings can be implemented: + +```mermaid +graph TD +A[AsyncAPI Document] --> B((Servers)) +A --> D((Channels)) +A --> E((Operations)) +D --> F((Messages)) +B --> C{Server Bindings} +D --> G{Channel Bindings} +E --> H{Operation Bindings} +F --> I{Message Bindings} + +style C fill:#47BCEE,stroke:#47BCEE; +style G fill:#47BCEE,stroke:#47BCEE; +style H fill:#47BCEE,stroke:#47BCEE; +style I fill:#47BCEE,stroke:#47BCEE; +``` + + +## Server bindings + +Server bindings provide protocol-specific information related to the server configuration. For example, if you use Pulsar as your message broker, you can specify the tenant name in the server bindings. + +Here is a diagram explaining server bindings: + +```mermaid +graph LR +A[AsyncAPI Document] --> B((Servers)) +B --> C{Server Bindings} + +style C fill:#47BCEE,stroke:#47BCEE; +``` + +This diagram shows where server bindings fit into the AsyncAPI document structure. + +The next example showcases how to use server bindings to detail protocol-specific configurations for the server: + +```yml +servers: + production: + bindings: + pulsar: + tenant: contoso + bindingVersion: '0.1.0' +``` + +The previous document shows how to set up server bindings for a server that is a Pulsar broker. + +## Channel bindings + +Channel bindings are used to specify protocol-specific information for a specific channel. For example, in Kafka, you can specify number of partitions for a given topic. + +Here is a diagram explaining where channel bindings fit into the AsyncAPI document structure: + +```mermaid +graph LR +A[AsyncAPI Document] --> D((Channels)) +D --> G{Channel Bindings} + +style G fill:#47BCEE,stroke:#47BCEE; +``` + + +Here is an example of using channel bindings to specify protocol-specific information for a specific channel: + +```yml +channels: + user-signedup: + bindings: + kafka: + topic: 'my-specific-topic-name' + partitions: 20 + replicas: 3 + topicConfiguration: + cleanup.policy: ["delete", "compact"] + retention.ms: 604800000 + retention.bytes: 1000000000 + delete.retention.ms: 86400000 + max.message.bytes: 1048588 + bindingVersion: '0.4.0' +``` + +The previous document shows how to configure channel bindings for a Kafka topic-representative channel. + +## Message bindings + +Message bindings provide protocol-specific information for a specific message. For example, for the AMQP protocol, you can specify the message type in a protocol-specific notation. + +Here is a diagram explaining where message bindings fit into the AsyncAPI document structure: + +```mermaid +graph LR +A[AsyncAPI Document] --> F((Channels)) +F --> G{Message Bindings} + +style G fill:#47BCEE,stroke:#47BCEE; +``` + + +Here is an example of using message bindings to provide protocol-specific information for a specific message: + +```yml +channels: + userSignup: + address: 'user/signup' + messages: + userSignupMessage: + bindings: + amqp: + contentEncoding: gzip + messageType: 'user.signup' + bindingVersion: 0.3.0 +``` + +The previous document shows how to set up message bindings for a message transported using the AMQP protocol. + +## Operation bindings + +Operation bindings allow you to specify protocol-specific information for a specific operation. For example, for MQTT, you can specify the quality of the service for a given operation. + +Here is a diagram explaining where operation bindings fit into the AsyncAPI document structure: + +```mermaid +graph LR +A[AsyncAPI Document] --> D((Channels)) +D --> E{Operations} +E --> H{Operation Bindings} + +style H fill:#47BCEE,stroke:#47BCEE; +``` + + +Here is an example of using operation bindings to specify protocol-specific information for a specific operation: + +```yml +channels: + user/signup: +operations: + userSignup: + action: receive + bindings: + mqtt: + qos: 2 + retain: true + bindingVersion: 0.2.0 +``` + +The previous document shows how to set up operation bindings for an operation that describes how an application that uses MQTT as transport, receives the message. + +Using bindings helps you enhance the AsyncAPI documentation with protocol-specific details, making it easier to understand and implement the API. From 8f5b024ef331cd84fe6d4b6b2f742482e3e00263 Mon Sep 17 00:00:00 2001 From: Rohit <108233235+TRohit20@users.noreply.github.com> Date: Thu, 16 Nov 2023 09:00:00 +0530 Subject: [PATCH 19/19] docs: adding document for servers' security (#2231) Co-authored-by: Alejandra Quetzalli %0ACo-authored-by: Lukasz Gornicki --- .../asyncapi-document/server-security.md | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/server-security.md diff --git a/pages/docs/concepts/asyncapi-document/server-security.md b/pages/docs/concepts/asyncapi-document/server-security.md new file mode 100644 index 00000000000..aeba878ad24 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/server-security.md @@ -0,0 +1,115 @@ +--- +title: Server Security +weight: 200 +--- + +Server security refers to the measures and practices implemented to protect servers from unauthorized access, data breaches, and other security threats. Server security involves implementing various security mechanisms to ensure the confidentiality, integrity, and availability of server resources. + +In the context of AsyncAPI, securing servers ensures secure exchange of messages between clients and servers. While also protecting sensitive data, preventing unauthorized access, and maintaining the overall security of the API or server. + +You can describe how is your server secured with `security` property where you define which security schemes can be used with the server in context. Each `server` in the AsyncAPI document can have one or more security schemes declared. A security scheme defines a security requirement that must be satisfied to authorize an operation, such as a API key or username and password. + +Here is a example of adding security to your server that shows that different server can have different security mechanisms: +```yml +asyncapi: 3.0.0 +info: + title: Streetlights Kafka API + version: 1.0.0 +servers: + scram-connections: + host: 'test.mykafkacluster.org:18092' + protocol: kafka-secure + description: Test broker secured with scramSha256 + security: + - $ref: '#/components/securitySchemes/saslScram' + mtls-connections: + host: 'test.mykafkacluster.org:28092' + protocol: kafka-secure + description: Test broker secured with X509 + security: + - $ref: '#/components/securitySchemes/certs' +components: + securitySchemes: + saslScram: + type: scramSha256 + description: Provide your username and password for SASL/SCRAM authentication + certs: + type: X509 + description: Download the certificate files from service provider +``` + +Here is a illustration of securing servers: +```mermaid +graph LR + C[servers] + F[host] + I[protocol] + E[security] + C --> F + C --> E + C --> I + style C fill:#47BCEE,stroke:#000; + style E fill:#47BCEE,stroke:#000 +``` + +Here are some of the security schemes that AsyncAPI supports: +- User/Password + ```yml + type: userPassword + ``` + +- API key (either as a user or as a password) + ```yml + type: apiKey + in: user + ``` + +- X.509 certificate + ```yml + type: X509 + ``` + +- End-to-end encryption (either symmetric or asymmetric) + ```yml + type: symmetricEncryption + ``` + +- HTTP authentication + ```yml + type: http + scheme: basic + ``` + +- HTTP API key + ```yml + type: httpApiKey + name: api_key + in: header + ``` + +- JWT Bearer + ```yml + type: http + scheme: bearer + bearerFormat: JWT + ``` + +- Implicit oauth2 + ```yml + type: oauth2 + flows: + implicit: + authorizationUrl: https://example.com/api/oauth/dialog + availableScopes: + write:pets: modify pets in your account + read:pets: read your pets + scopes: + - 'write:pets' + ``` + +- SASL (Simple Authentication and Security Layer) as defined in RFC4422 + ```yml + type: scramSha512 + ``` + +Although, the `security` property is not mandatory to be implemented, it is a good practise to always secure your server(s) in production. Similarly, having multiple security schemes declared does not necessarily mean that the server is more secure, it really depends on other factors such as the protocol used, use case, business perspective and more. Additionally, you can also [add security on the `operation` level](securing-operations)