diff --git a/.github/workflows/automerge.yml b/.github/workflows/automerge.yml index 9253675cd66..116b80652db 100644 --- a/.github/workflows/automerge.yml +++ b/.github/workflows/automerge.yml @@ -45,7 +45,7 @@ jobs: env: GITHUB_TOKEN: "${{ secrets.GH_TOKEN }}" GITHUB_LOGIN: asyncapi-bot - MERGE_LABELS: "" + MERGE_LABELS: "!do-not-merge" MERGE_METHOD: "squash" MERGE_COMMIT_MESSAGE: "{pullRequest.title} (#{pullRequest.number})" MERGE_RETRIES: "20" diff --git a/README.md b/README.md index a2a34293925..c9eb0a45478 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,6 @@ Use the following tools to set up the project: - [Node.js](https://nodejs.org/) v16.0.0+ - [npm](https://www.npmjs.com/) v7.10.0+ - ## Run locally 1. Fork the repository by clicking on `Fork` option on top right of the main repository. diff --git a/components/Asyncapi3Comparison.js b/components/Asyncapi3Comparison.js new file mode 100644 index 00000000000..cc9c273b396 --- /dev/null +++ b/components/Asyncapi3Comparison.js @@ -0,0 +1,501 @@ +import React, { useState } from 'react'; + +/** + * 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 +
+
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 + +
+
+ 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, + Schema: 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 +
+
setHoverState(prevState => ({ ...prevState, Schema: true }))} onMouseLeave={() => setHoverState({ Schema: false })}> + 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 +
+
setHoverState(prevState => ({ ...prevState, Schema: true }))} onMouseLeave={() => setHoverState({ Schema: false })}> + schema +
+
+
+
+
+
+
+
+
+
+
+
+ ) +} + +/** + * Compares how the parameter object changed location from v2 to v3 + */ +export function Asyncapi3ParameterComparison({ className = '' }) { + const [hoverState, setHoverState] = useState({ + location: false, + description: false, + enum: false, + examples: false, + default: false + }); + + return ( +
+
+

AsyncAPI 2.x

+ +
+
+ components | channels + +
+
+ parameters + +
+
+ parameter +
+
setHoverState(prevState => ({ ...prevState, location: true }))} onMouseLeave={() => setHoverState({ location: false })}> + location +
+
setHoverState(prevState => ({ ...prevState, description: true }))} onMouseLeave={() => setHoverState({ description: false })}> + description +
+ +
+ schema +
+
type
+
setHoverState(prevState => ({ ...prevState, enum: true }))} onMouseLeave={() => setHoverState({ enum: false })}> + enum +
+
setHoverState(prevState => ({ ...prevState, examples: true }))} onMouseLeave={() => setHoverState({ examples: false })}> + examples +
+
setHoverState(prevState => ({ ...prevState, default: true }))} onMouseLeave={() => setHoverState({ default: false })}> + default +
+
setHoverState(prevState => ({ ...prevState, description: true }))} onMouseLeave={() => setHoverState({ description: false })}> + description +
+
pattern
+
multipleOf
+
And all other properties
+
+
+
+
+
+
+
+
+
+
+
+

AsyncAPI 3.0

+ +
+
+ components | channels + +
+
+ parameters + +
+
+ parameter +
+
setHoverState(prevState => ({ ...prevState, location: true }))} onMouseLeave={() => setHoverState({ location: false })}> + location +
+
setHoverState(prevState => ({ ...prevState, description: true }))} onMouseLeave={() => setHoverState({ description: false })}> + description +
+
setHoverState(prevState => ({ ...prevState, enum: true }))} onMouseLeave={() => setHoverState({ enum: false })}> + enum +
+
setHoverState(prevState => ({ ...prevState, examples: true }))} onMouseLeave={() => setHoverState({ examples: false })}> + examples +
+
setHoverState(prevState => ({ ...prevState, default: true }))} onMouseLeave={() => setHoverState({ default: false })}> + default +
+
+
+
+
+
+
+
+
+
+ ) +} 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
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/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/components/campaigns/AnnoucementHero.js b/components/campaigns/AnnoucementHero.js index 39153357bfc..26e227297ed 100644 --- a/components/campaigns/AnnoucementHero.js +++ b/components/campaigns/AnnoucementHero.js @@ -3,7 +3,7 @@ import Paragraph from '../typography/Paragraph' import Button from '../buttons/Button' import Heading from '../typography/Heading' import Container from '../layout/Container' -import AnnouncementRemainingDays from './AnnouncementRamainingDays' +import AnnouncementRemainingDays from './AnnouncementRemainingDays' import ArrowLeft from '../icons/ArrowLeft' import ArrowRight from '../icons/ArrowRight' @@ -25,7 +25,7 @@ export default function AnnouncementHero({ className = '', small = false, hideVi const [activeIndex, setActiveIndex] = useState(0); const cfpDeadlineIndia = '2023-11-30T06:00:00Z' - const cfpDeadlineFrance = '2023-12-6T06:00:00Z' + const cfpDeadlineFrance = '2023-12-06T06:00:00Z' const showBannerIndia = shouldShowBanner(cfpDeadlineIndia); const showBannerFrance = shouldShowBanner(cfpDeadlineFrance); @@ -33,7 +33,7 @@ export default function AnnouncementHero({ className = '', small = false, hideVi return (
-
-
- -
-
-
- {banners.map((banner, index) => ( - banner.show && ( - - ) - ))} -
-
- {banners.map((banner, index) => ( -
goToIndex(index)} - /> - ))} -
-
-
- -
-
- - ); + return '' + // return ( + // + //
+ //
+ // + //
+ //
+ //
+ // {banners.map((banner, index) => ( + // banner.show && ( + // + // ) + // ))} + //
+ //
+ // {banners.map((banner, index) => ( + //
goToIndex(index)} + // /> + // ))} + //
+ //
+ //
+ // + //
+ //
+ // + // ); } diff --git a/components/campaigns/AnnouncementRamainingDays.js b/components/campaigns/AnnouncementRemainingDays.js similarity index 100% rename from components/campaigns/AnnouncementRamainingDays.js rename to components/campaigns/AnnouncementRemainingDays.js diff --git a/components/campaigns/Banner.js b/components/campaigns/Banner.js index 28e309ce9ef..4c4e07e7e6c 100644 --- a/components/campaigns/Banner.js +++ b/components/campaigns/Banner.js @@ -12,9 +12,8 @@ export default function Banner({}) { const day = new Date().getUTCDate(); const month = new Date().getUTCMonth(); const year = new Date().getUTCFullYear(); - - // month=10 is November. Show only between 6-30 November. - if (year > 2022 || month !== 10 || day < 6) { + // month=11 is December. Show only between 6-31 December. + if (year > 2023 || month > 11 || day < 6) { return null; } @@ -22,27 +21,27 @@ export default function Banner({}) {
-
+

- AsyncAPI Conference 2022 has ended! ⭐️ - -

-
-
-

- - AsyncAPI Conference 2022 has ended. Good news: you can still watch the recording! ⭐️ + AsyncAPI v3 has landed! ⭐️

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/NavBar.js b/components/navigation/NavBar.js index 630e74aadf6..dd9dcbe3574 100644 --- a/components/navigation/NavBar.js +++ b/components/navigation/NavBar.js @@ -104,8 +104,8 @@ export default function NavBar({ return (
- Skip to main content -
+ {/* Skip to main content */} +
{!hideLogo && (
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/config/MAINTAINERS.json b/config/MAINTAINERS.json index 672d3db2e88..6acfc95602f 100644 --- a/config/MAINTAINERS.json +++ b/config/MAINTAINERS.json @@ -338,6 +338,18 @@ "jasyncapi-idea-plugin" ] }, + { + "name": "Prince Rajpoot", + "github": "princerajpoot20", + "linkedin": "princerajpoot", + "slack": "U04STTQHV18", + "twitter": "iamPrince_2003", + "availableForHire": true, + "isTscMember": true, + "repos": [ + "studio" + ] + }, { "name": "Richard Coppen", "github": "rcoppen", diff --git a/config/all-tags.json b/config/all-tags.json index 3ef0bff50ef..d9fbea47635 100644 --- a/config/all-tags.json +++ b/config/all-tags.json @@ -1 +1 @@ -{"languages":[{"name":"Go/Golang","color":"bg-[#8ECFDF]","borderColor":"border-[#00AFD9]"},{"name":"Java","color":"bg-[#ECA2A4]","borderColor":"border-[#EC2125]"},{"name":"JavaScript","color":"bg-[#F2F1C7]","borderColor":"border-[#BFBE86]"},{"name":"HTML","color":"bg-[#E2A291]","borderColor":"border-[#E44D26]"},{"name":"C/C++","color":"bg-[#93CDEF]","borderColor":"border-[#0080CC]"},{"name":"C#","color":"bg-[#E3AFE0]","borderColor":"border-[#9B4F96]"},{"name":"Python","color":"bg-[#A8D0EF]","borderColor":"border-[#3878AB]"},{"name":"TypeScript","color":"bg-[#7DBCFE]","borderColor":"border-[#2C78C7]"},{"name":"Kotlin","color":"bg-[#B1ACDF]","borderColor":"border-[#756BD9]"},{"name":"Scala","color":"bg-[#FFA299]","borderColor":"border-[#DF301F]"},{"name":"Markdown","color":"bg-[#BABEBF]","borderColor":"border-[#445B64]"},{"name":"YAML","color":"bg-[#FFB764]","borderColor":"border-[#F1901F]"},{"name":"R","color":"bg-[#84B5ED]","borderColor":"border-[#246BBE]"},{"name":"Ruby","color":"bg-[#FF8289]","borderColor":"border-[#FF000F]"},{"name":"Rust","color":"bg-[#FFB8AA]","borderColor":"border-[#E43716]"},{"name":"Shell","color":"bg-[#87D4FF]","borderColor":"border-[#389ED7]"},{"name":"Groovy","color":"bg-[#B6D5E5]","borderColor":"border-[#609DBC]"}],"technologies":[{"name":"Node.js","color":"bg-[#BDFF67]","borderColor":"border-[#84CE24]"},{"name":"Hermes","color":"bg-[#8AEEBD]","borderColor":"border-[#2AB672]"},{"name":"React JS","color":"bg-[#9FECFA]","borderColor":"border-[#08D8FE]"},{"name":".NET","color":"bg-[#A184FF]","borderColor":"border-[#5026D4]"},{"name":"ASP.NET","color":"bg-[#71C2FB]","borderColor":"border-[#1577BC]"},{"name":"Springboot","color":"bg-[#98E279]","borderColor":"border-[#68BC44]"},{"name":"AWS","color":"bg-[#FF9F59]","borderColor":"border-[#EF6703]"},{"name":"Docker","color":"bg-[#B8E0FF]","borderColor":"border-[#2596ED]"},{"name":"Node-RED","color":"bg-[#FF7474]","borderColor":"border-[#8F0101]"},{"name":"Maven","color":"bg-[#FF6B80]","borderColor":"border-[#CA1A33]"},{"name":"Saas","color":"bg-[#6AB8EC]","borderColor":"border-[#2275AD]"},{"name":"Kubernetes-native","color":"bg-[#D7C7F2]","borderColor":"border-[#A387D2]"},{"name":"Scala","color":"bg-[#D7C7F2]","borderColor":"border-[#A387D2]"},{"name":"Azure","color":"bg-[#4B93FF]","borderColor":"border-[#015ADF]"},{"name":"Jenkins","color":"bg-[#D7C7F2]","borderColor":"border-[#A387D2]"},{"name":"Flask","color":"bg-[#D7C7F2]","borderColor":"border-[#A387D2]"},{"name":"Nest Js","color":"bg-[#E1224E]","borderColor":"border-[#B9012b]"},{"name":"TypeScript","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Socket.IO","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Liquid","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Kotlin","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Gradle","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Spring Cloud Streams","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"JHipster JDL","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Groovy","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Markdown","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Shell","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"WebComponents","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Babel","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Storybook","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"AsyncAPI Generator","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"JetBrains","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"IntelliJ IDEA","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"VSCode","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"SmartPaste","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"HTML","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"}]} \ No newline at end of file +{"languages":[{"name":"Go/Golang","color":"bg-[#8ECFDF]","borderColor":"border-[#00AFD9]"},{"name":"Java","color":"bg-[#ECA2A4]","borderColor":"border-[#EC2125]"},{"name":"JavaScript","color":"bg-[#F2F1C7]","borderColor":"border-[#BFBE86]"},{"name":"HTML","color":"bg-[#E2A291]","borderColor":"border-[#E44D26]"},{"name":"C/C++","color":"bg-[#93CDEF]","borderColor":"border-[#0080CC]"},{"name":"C#","color":"bg-[#E3AFE0]","borderColor":"border-[#9B4F96]"},{"name":"Python","color":"bg-[#A8D0EF]","borderColor":"border-[#3878AB]"},{"name":"TypeScript","color":"bg-[#7DBCFE]","borderColor":"border-[#2C78C7]"},{"name":"Kotlin","color":"bg-[#B1ACDF]","borderColor":"border-[#756BD9]"},{"name":"Scala","color":"bg-[#FFA299]","borderColor":"border-[#DF301F]"},{"name":"Markdown","color":"bg-[#BABEBF]","borderColor":"border-[#445B64]"},{"name":"YAML","color":"bg-[#FFB764]","borderColor":"border-[#F1901F]"},{"name":"R","color":"bg-[#84B5ED]","borderColor":"border-[#246BBE]"},{"name":"Ruby","color":"bg-[#FF8289]","borderColor":"border-[#FF000F]"},{"name":"Rust","color":"bg-[#FFB8AA]","borderColor":"border-[#E43716]"},{"name":"Shell","color":"bg-[#87D4FF]","borderColor":"border-[#389ED7]"},{"name":"Groovy","color":"bg-[#B6D5E5]","borderColor":"border-[#609DBC]"}],"technologies":[{"name":"Node.js","color":"bg-[#BDFF67]","borderColor":"border-[#84CE24]"},{"name":"Hermes","color":"bg-[#8AEEBD]","borderColor":"border-[#2AB672]"},{"name":"React JS","color":"bg-[#9FECFA]","borderColor":"border-[#08D8FE]"},{"name":".NET","color":"bg-[#A184FF]","borderColor":"border-[#5026D4]"},{"name":"ASP.NET","color":"bg-[#71C2FB]","borderColor":"border-[#1577BC]"},{"name":"Springboot","color":"bg-[#98E279]","borderColor":"border-[#68BC44]"},{"name":"AWS","color":"bg-[#FF9F59]","borderColor":"border-[#EF6703]"},{"name":"Docker","color":"bg-[#B8E0FF]","borderColor":"border-[#2596ED]"},{"name":"Node-RED","color":"bg-[#FF7474]","borderColor":"border-[#8F0101]"},{"name":"Maven","color":"bg-[#FF6B80]","borderColor":"border-[#CA1A33]"},{"name":"Saas","color":"bg-[#6AB8EC]","borderColor":"border-[#2275AD]"},{"name":"Kubernetes-native","color":"bg-[#D7C7F2]","borderColor":"border-[#A387D2]"},{"name":"Scala","color":"bg-[#D7C7F2]","borderColor":"border-[#A387D2]"},{"name":"Azure","color":"bg-[#4B93FF]","borderColor":"border-[#015ADF]"},{"name":"Jenkins","color":"bg-[#D7C7F2]","borderColor":"border-[#A387D2]"},{"name":"Flask","color":"bg-[#D7C7F2]","borderColor":"border-[#A387D2]"},{"name":"Nest Js","color":"bg-[#E1224E]","borderColor":"border-[#B9012b]"},{"name":"TypeScript","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Socket.IO","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Liquid","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Kotlin","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Gradle","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Spring Cloud Streams","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"JHipster JDL","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Groovy","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Markdown","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Shell","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"WebComponents","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Babel","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"Storybook","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"AsyncAPI Generator","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"VSCode","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"SmartPaste","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"JetBrains","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"IntelliJ IDEA","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"},{"name":"HTML","color":"bg-[#61d0f2]","borderColor":"border-[#40ccf7]"}]} \ No newline at end of file diff --git a/config/meetings.json b/config/meetings.json index 72611212193..51651ed1f18 100644 --- a/config/meetings.json +++ b/config/meetings.json @@ -1,11 +1,4 @@ [ - { - "title": "Spec 3.0 Docs Meeting", - "calLink": "https://www.google.com/calendar/event?eid=cG9iOHNqZGlrbmg4cnUxanMzMTgyN3AxdnMgY19xOXRzZWlnbG9tZHNqNm5qdWh2YnB0czExY0Bn", - "url": "https://github.com/asyncapi/community/issues/792", - "banner": "", - "date": "2023-08-17T14:30:00.000Z" - }, { "title": "Spec 3.0 Docs Meeting", "calLink": "https://www.google.com/calendar/event?eid=aHJwdnA1bzI1ajVjNzliZ2h2bm1nZnI3b3MgY19xOXRzZWlnbG9tZHNqNm5qdWh2YnB0czExY0Bn", @@ -13,34 +6,6 @@ "banner": "", "date": "2023-08-31T14:30:00.000Z" }, - { - "title": "Community Meeting", - "calLink": "https://www.google.com/calendar/event?eid=YmlybTZwODdmMzBnNGg0b3J1OWxmdnBxNmMgY19xOXRzZWlnbG9tZHNqNm5qdWh2YnB0czExY0Bn", - "url": "https://github.com/asyncapi/community/issues/818", - "banner": "https://user-images.githubusercontent.com/40604284/256949583-958c34c8-4256-4ac5-852b-e00ec094fad0.png", - "date": "2023-08-08T16:00:00.000Z" - }, - { - "title": "Spec 3.0 Meeting", - "calLink": "https://www.google.com/calendar/event?eid=NG9lc2RwN3A2djFmNmRxaHZoaWRjMnRhaDAgY19xOXRzZWlnbG9tZHNqNm5qdWh2YnB0czExY0Bn", - "url": "https://github.com/asyncapi/community/issues/823", - "banner": "", - "date": "2023-08-02T16:00:00.000Z" - }, - { - "title": "Community Meeting", - "calLink": "https://www.google.com/calendar/event?eid=Z3YzNDRwamprYzMwNTluYTdtNG1iaHA5NjggY19xOXRzZWlnbG9tZHNqNm5qdWh2YnB0czExY0Bn", - "url": "https://github.com/asyncapi/community/issues/845", - "banner": "https://user-images.githubusercontent.com/40604284/260686941-20c44493-65de-4a09-9dac-a8f7d1f0fcaf.png", - "date": "2023-08-22T08:00:00.000Z" - }, - { - "title": "Spec 3.0 Meeting", - "calLink": "https://www.google.com/calendar/event?eid=Y281MHE2dGo1ZmE1cmtobmtyOGYzb3VsazAgY19xOXRzZWlnbG9tZHNqNm5qdWh2YnB0czExY0Bn", - "url": "https://github.com/asyncapi/community/issues/847", - "banner": "", - "date": "2023-08-23T16:00:00.000Z" - }, { "title": "Spec 3.0 Meeting", "calLink": "https://www.google.com/calendar/event?eid=NDEzM2E1ZGE5YWttYXVpYW9zbTl1cWM1YWMgY19xOXRzZWlnbG9tZHNqNm5qdWh2YnB0czExY0Bn", @@ -131,5 +96,31 @@ "url": "https://github.com/asyncapi/community/issues/918", "banner": "https://user-images.githubusercontent.com/40604284/277314435-ec985247-c575-4449-9f79-442b3077541a.png", "date": "2023-11-28T16:00:00.000Z" + }, + { + "title": "Community Meeting", + "calLink": "https://www.google.com/calendar/event?eid=M2I4MXRidmpqb2ZyZTUyajhsZm41ZjN0bTggY19xOXRzZWlnbG9tZHNqNm5qdWh2YnB0czExY0Bn", + "url": "https://github.com/asyncapi/community/issues/979", + "banner": "https://user-images.githubusercontent.com/40604284/288050762-4d064212-22ea-4af0-9d1a-b23c8fd70d6b.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTEiLCJleHAiOjE3MDE3ODI2MDUsIm5iZiI6MTcwMTc4MjMwNSwicGF0aCI6Ii80MDYwNDI4NC8yODgwNTA3NjItNGQwNjQyMTItMjJlYS00YWYwLTlkMWEtYjIzYzhmZDcwZDZiLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFJV05KWUFYNENTVkVINTNBJTJGMjAyMzEyMDUlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjMxMjA1VDEzMTgyNVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWYzOGFhZmI5NzAxODljZDQ4NTFhNDc0NGIxNGQzZDZlZmU3ZjhhYTExOGU1YTRkN2FjODU1MzgzZGU0M2UzNmMmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.-FT5AFf2Np1cFxMyXVga0zAfLjFc9fspwL-BJ_t7KLg", + "date": "2023-12-12T08:00:00.000Z" + }, + { + "title": "Overview of AyncAPI v3", + "calLink": "https://www.google.com/calendar/event?eid=c3E0Ym1qMTFnMDY5ODljdGk1ajh2anRrdjAgY19xOXRzZWlnbG9tZHNqNm5qdWh2YnB0czExY0Bn", + "url": "https://github.com/asyncapi/community/issues/981", + "banner": "https://user-images.githubusercontent.com/40604284/285945520-e06ff77c-0e37-432e-964d-b4d47167cc18.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTEiLCJleHAiOjE3MDE3ODI1NzUsIm5iZiI6MTcwMTc4MjI3NSwicGF0aCI6Ii80MDYwNDI4NC8yODU5NDU1MjAtZTA2ZmY3N2MtMGUzNy00MzJlLTk2NGQtYjRkNDcxNjdjYzE4LnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFJV05KWUFYNENTVkVINTNBJTJGMjAyMzEyMDUlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjMxMjA1VDEzMTc1NVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWY5MjBhNTEwMjIwNDQxNzczY2EyMDI1YjQzOWIwYzRhY2MxNTU3ZDYyMGY2NzMxYjVkYzYyNmViZTM5Yjg4ZTEmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.Dm-WJy2AQO2xUMAJ1nO6ADZuBFYXKj0NEFgdcDd44Fg", + "date": "2023-12-19T13:00:00.000Z" + }, + { + "title": "AsyncAPI v3 announcement", + "calLink": "https://www.google.com/calendar/event?eid=NmhzMGZnNTRnZHNnZTFtbnRjbmhpZnJzbjAgY19xOXRzZWlnbG9tZHNqNm5qdWh2YnB0czExY0Bn", + "date": "2023-12-06T15:00:00.000Z" + }, + { + "title": "3 Request/Reply Use Cases", + "calLink": "https://www.google.com/calendar/event?eid=b3NvM2c0dW9tcTk1djRiMDJmbWU4dG9odGcgY19xOXRzZWlnbG9tZHNqNm5qdWh2YnB0czExY0Bn", + "url": "https://github.com/asyncapi/community/issues/985", + "banner": "https://user-images.githubusercontent.com/40604284/288488243-e274e624-c5b3-4bff-b0ec-8c1929a24aae.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTEiLCJleHAiOjE3MDE4ODI2MTUsIm5iZiI6MTcwMTg4MjMxNSwicGF0aCI6Ii80MDYwNDI4NC8yODg0ODgyNDMtZTI3NGU2MjQtYzViMy00YmZmLWIwZWMtOGMxOTI5YTI0YWFlLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFJV05KWUFYNENTVkVINTNBJTJGMjAyMzEyMDYlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjMxMjA2VDE3MDUxNVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWUyMGYyNDE3Nzg4OGUyZGVmYjNlMDkxYzVkOWFkNjEwYjM4ZDI2YzZjZmUyYjRjMDliMDQ3YWJiNTVlNDI1MmQmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.jYmY72ZRresQv1lMFeKwA49Wi6VkAozRpIHH4uE0J8g", + "date": "2023-12-14T18:00:00.000Z" } ] \ No newline at end of file diff --git a/config/newsroom_videos.json b/config/newsroom_videos.json index 40a17f976d6..0f91f4dda66 100644 --- a/config/newsroom_videos.json +++ b/config/newsroom_videos.json @@ -1,32 +1,32 @@ [ { - "image_url": "https://i.ytimg.com/vi/Vm4ZKFb2PVE/hqdefault.jpg", - "title": "Community Meeting(October 31th, 2023)", - "description": "Powered by Restream https://restream.io https://github.com/asyncapi/community/issues/916.", - "videoId": "Vm4ZKFb2PVE" + "image_url": "https://i.ytimg.com/vi/g6CPg77Lf5Q/hqdefault.jpg", + "title": "AsyncAPI Conf on Tour 2023 in Bangalore, India", + "description": "AACoT'23 Bangalore Edition live from Postman Offices in India.", + "videoId": "g6CPg77Lf5Q" }, { - "image_url": "https://i.ytimg.com/vi/FN5eR1Zqh9c/hqdefault.jpg", - "title": "AsyncAPI Conf on Tour 2023 in Madrid", - "description": "AACoT'23 Madrid Edition streamed live from StageOne at SNGULAR. 00:00 Waiting 57:12 Opening 1:26:07 Everything You Wish ...", - "videoId": "FN5eR1Zqh9c" + "image_url": "https://i.ytimg.com/vi/p68PUXDMsks/hqdefault.jpg", + "title": "Community Meeting(November 28th, 2023)", + "description": "https://github.com/asyncapi/community/issues/918.", + "videoId": "p68PUXDMsks" }, { - "image_url": "https://i.ytimg.com/vi/zSbv4ibqYds/hqdefault.jpg", - "title": "Community Meeting(October 17th, 2023)", - "description": "https://github.com/asyncapi/community/issues/912.", - "videoId": "zSbv4ibqYds" + "image_url": "https://i.ytimg.com/vi/KDort611FNg/hqdefault.jpg", + "title": "Community Meeting(November 14th, 2023)", + "description": "https://github.com/asyncapi/community/issues/917.", + "videoId": "KDort611FNg" }, { - "image_url": "https://i.ytimg.com/vi/KTnFoXY_evs/hqdefault.jpg", - "title": "Hacktoberfest (October 6th, 2023)", - "description": "https://github.com/asyncapi/community/issues/894.", - "videoId": "KTnFoXY_evs" + "image_url": "https://i.ytimg.com/vi/YREb9wuYCOA/hqdefault.jpg", + "title": "AsyncAPI v3 announcement", + "description": "Join us live to learn about all the goodies that AsyncAPI v3 brings.", + "videoId": "YREb9wuYCOA" }, { - "image_url": "https://i.ytimg.com/vi/qjMojQ-fFew/hqdefault.jpg", - "title": "Spec 3.0 docs meeting (September 28, 2023)", - "description": "https://github.com/asyncapi/community/issues/885.", - "videoId": "qjMojQ-fFew" + "image_url": "https://i.ytimg.com/vi/Vm4ZKFb2PVE/hqdefault.jpg", + "title": "Community Meeting(October 31th, 2023)", + "description": "Powered by Restream https://restream.io https://github.com/asyncapi/community/issues/916.", + "videoId": "Vm4ZKFb2PVE" } ] \ No newline at end of file diff --git a/config/tools-automated.json b/config/tools-automated.json index c43ce240bf9..e4d8bdb7790 100644 --- a/config/tools-automated.json +++ b/config/tools-automated.json @@ -420,41 +420,41 @@ "description": "The following is a list of tools that compare AsyncAPI documents.", "toolsList": [ { - "title": "jasyncapicmp", - "description": "Tool for comparing two AsyncAPI versions and evaluating compatibility.", + "title": "AsyncAPI Diff", + "description": "Diff is a library that compares two AsyncAPI Documents and provides information about the differences by pointing out explicitly information like breaking changes.", "links": { - "websiteUrl": "https://siom79.github.io/jasyncapicmp/", - "docsUrl": "https://github.com/siom79/jasyncapicmp", - "repoUrl": "https://github.com/siom79/jasyncapicmp" + "repoUrl": "https://github.com/asyncapi/diff" }, "filters": { - "language": "Java", + "language": "TypeScript", "technology": [ - "Maven" + "TypeScript" ], "categories": [ "compare-tool" ], "hasCommercial": false, - "isAsyncAPIOwner": false + "isAsyncAPIOwner": true } }, { - "title": "AsyncAPI Diff", - "description": "Diff is a library that compares two AsyncAPI Documents and provides information about the differences by pointing out explicitly information like breaking changes.", + "title": "jasyncapicmp", + "description": "Tool for comparing two AsyncAPI versions and evaluating compatibility.", "links": { - "repoUrl": "https://github.com/asyncapi/diff" + "websiteUrl": "https://siom79.github.io/jasyncapicmp/", + "docsUrl": "https://github.com/siom79/jasyncapicmp", + "repoUrl": "https://github.com/siom79/jasyncapicmp" }, "filters": { - "language": "TypeScript", + "language": "Java", "technology": [ - "TypeScript" + "Maven" ], "categories": [ "compare-tool" ], "hasCommercial": false, - "isAsyncAPIOwner": true + "isAsyncAPIOwner": false } } ] @@ -462,25 +462,6 @@ "CLIs": { "description": "The following is a list of tools that you can work with in terminal or do some CI/CD automation.", "toolsList": [ - { - "title": "AsyncAPI CLI", - "description": "One CLI to rule them all. \nThis is a CLI that aims to integrate all AsyncAPI tools that you need while AsyncAPI document development and maintainance. \nYou can use it to generate docs or code, validate AsyncAPI document and event create new documents.\n", - "links": { - "websiteUrl": "https://www.asyncapi.com/tools/cli", - "repoUrl": "https://github.com/asyncapi/cli" - }, - "filters": { - "technology": [ - "TypeScript" - ], - "categories": [ - "others", - "cli" - ], - "hasCommercial": false, - "isAsyncAPIOwner": true - } - }, { "title": "ZenWave SDK", "description": "DDD and API-First for Event-Driven Microservices", @@ -507,6 +488,25 @@ "isAsyncAPIOwner": false } }, + { + "title": "AsyncAPI CLI", + "description": "One CLI to rule them all. \nThis is a CLI that aims to integrate all AsyncAPI tools that you need while AsyncAPI document development and maintainance. \nYou can use it to generate docs or code, validate AsyncAPI document and event create new documents.\n", + "links": { + "websiteUrl": "https://www.asyncapi.com/tools/cli", + "repoUrl": "https://github.com/asyncapi/cli" + }, + "filters": { + "technology": [ + "TypeScript" + ], + "categories": [ + "others", + "cli" + ], + "hasCommercial": false, + "isAsyncAPIOwner": true + } + }, { "title": "AsyncAPI CLI", "description": "One CLI to rule them all. \nThis is a CLI that aims to integrate all AsyncAPI tools that you need while AsyncAPI document development and maintainance. \nYou can use it to generate docs or code, validate AsyncAPI document and event create new documents.\n", @@ -555,18 +555,15 @@ "description": "The following is a list of extensions for different IDEs like VSCode, IntelliJ IDEA and others", "toolsList": [ { - "title": "jAsyncAPI - IDEA plugin", - "description": "Idea plugin for the java-asyncapi - Helps to edit and validate AsyncAPI schemas.", + "title": "asyncapi-preview", + "description": "VSCode extension that enables you to:\n - Preview documentation generated using you AsyncAPI document. It uses AsyncAPI React component under the hood,\n - Create AsyncAPI documents faster using SmartPaste functionality\n", "links": { - "websiteUrl": "https://plugins.jetbrains.com/plugin/15673-asyncapi", - "docsUrl": "https://github.com/asyncapi/jasyncapi-idea-plugin#usage", - "repoUrl": "https://github.com/asyncapi/jasyncapi-idea-plugin" + "repoUrl": "https://github.com/asyncapi/vs-asyncapi-preview" }, "filters": { - "language": "Kotlin", "technology": [ - "JetBrains", - "IntelliJ IDEA" + "VSCode", + "SmartPaste" ], "categories": [ "ide-extension" @@ -576,15 +573,18 @@ } }, { - "title": "asyncapi-preview", - "description": "VSCode extension that enables you to:\n - Preview documentation generated using you AsyncAPI document. It uses AsyncAPI React component under the hood,\n - Create AsyncAPI documents faster using SmartPaste functionality\n", + "title": "jAsyncAPI - IDEA plugin", + "description": "Idea plugin for the java-asyncapi - Helps to edit and validate AsyncAPI schemas.", "links": { - "repoUrl": "https://github.com/asyncapi/vs-asyncapi-preview" + "websiteUrl": "https://plugins.jetbrains.com/plugin/15673-asyncapi", + "docsUrl": "https://github.com/asyncapi/jasyncapi-idea-plugin#usage", + "repoUrl": "https://github.com/asyncapi/jasyncapi-idea-plugin" }, "filters": { + "language": "Kotlin", "technology": [ - "VSCode", - "SmartPaste" + "JetBrains", + "IntelliJ IDEA" ], "categories": [ "ide-extension" @@ -617,15 +617,15 @@ "description": "The following is a list of templates compatible with AsyncAPI Generator. You can use them to generate apps, clients or documentation from your AsyncAPI documents.", "toolsList": [ { - "title": "HTML Template", - "description": "HTML template for AsyncAPI Generator. Use it to generate a static docs. It is using AsyncAPI React component under the hood.", + "title": "Node.js Multiprotocol Template", + "description": "This template generates a server using your AsyncAPI document. It supports multiple different protocols, like Kafka or MQTT. It is designed in the way that generated code is a library and with it's API you can start the server, send messages or register a middleware for listening incoming messages. Runtime message validation included.", "links": { - "repoUrl": "https://github.com/asyncapi/html-template" + "repoUrl": "https://github.com/asyncapi/nodejs-template" }, "filters": { "language": "javascript", "technology": [ - "HTML" + "Node.js" ], "categories": [ "generator-template" @@ -653,15 +653,15 @@ } }, { - "title": "Node.js Multiprotocol Template", - "description": "This template generates a server using your AsyncAPI document. It supports multiple different protocols, like Kafka or MQTT. It is designed in the way that generated code is a library and with it's API you can start the server, send messages or register a middleware for listening incoming messages. Runtime message validation included.", + "title": "HTML Template", + "description": "HTML template for AsyncAPI Generator. Use it to generate a static docs. It is using AsyncAPI React component under the hood.", "links": { - "repoUrl": "https://github.com/asyncapi/nodejs-template" + "repoUrl": "https://github.com/asyncapi/html-template" }, "filters": { "language": "javascript", "technology": [ - "Node.js" + "HTML" ], "categories": [ "generator-template" 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/cypress/test/components/campaignTests/AnnouncementRemainingDays.cy.js b/cypress/test/components/campaignTests/AnnouncementRemainingDays.cy.js index 925a0222be1..efdeadb4e11 100644 --- a/cypress/test/components/campaignTests/AnnouncementRemainingDays.cy.js +++ b/cypress/test/components/campaignTests/AnnouncementRemainingDays.cy.js @@ -1,6 +1,6 @@ import moment from 'moment'; import { mount } from '@cypress/react'; -import AnnouncementRemainingDays from '../../../../components/campaigns/AnnouncementRamainingDays'; +import AnnouncementRemainingDays from '../../../../components/campaigns/AnnouncementRemainingDays'; describe('AnnouncementRemainingDays', () => { it('displays correct countdown text', () => { diff --git a/cypress/test/pages/community/dashboard.cy.js b/cypress/test/pages/community/dashboard.cy.js index da33c1cc006..610155d4631 100644 --- a/cypress/test/pages/community/dashboard.cy.js +++ b/cypress/test/pages/community/dashboard.cy.js @@ -22,7 +22,7 @@ describe('Integration Test for Dashboard ', () => { cy.contains('asyncapi/generator'); cy.contains('docs') //check if this is not selected options are not displayed - cy.should('not.contain', 'asyncapi/community'); - cy.should('not.contain', 'javascript'); + // cy.should('not.contain', 'asyncapi/community'); + // cy.should('not.contain', 'javascript'); }); }); \ No newline at end of file diff --git a/cypress/test/scripts/build-newsroom-videos.cy.js b/cypress/test/scripts/build-newsroom-videos.cy.js index ec27f76981c..d1789ec50e9 100644 --- a/cypress/test/scripts/build-newsroom-videos.cy.js +++ b/cypress/test/scripts/build-newsroom-videos.cy.js @@ -44,7 +44,7 @@ describe('Newsroom Videos', () => { }).as('getYoutubeVideos'); // Manually trigger the function - await buildNewsroomVideos().then((videoData) => { + cy.invoke(buildNewsroomVideos()).then((videoData) => { expect(videoData).to.exist; }); }); diff --git a/dashboard.json b/dashboard.json index 7127999f2d0..bc7e99f50fe 100644 --- a/dashboard.json +++ b/dashboard.json @@ -16,22 +16,6 @@ ], "score": 54.2759972736099 }, - { - "id": "MDU6SXNzdWUzNjkwNDExMDc=", - "isPR": false, - "isAssigned": false, - "title": "Support request/reply pattern", - "author": "adrianhopebailie", - "resourcePath": "/asyncapi/spec/issues/94", - "repo": "asyncapi/spec", - "labels": [ - { - "name": "keep-open", - "color": "fce250" - } - ], - "score": 41.64031536864252 - }, { "id": "PR_kwDOBW5R_c5Xb72L", "isPR": true, @@ -41,18 +25,54 @@ "resourcePath": "/asyncapi/website/pull/2038", "repo": "asyncapi/website", "labels": [], - "score": 39.63009324739771 + "score": 41.35314077989326 }, { - "id": "PR_kwDOFLhIt85Vmgtj", + "id": "I_kwDOFLhIt84-OUI3", + "isPR": false, + "isAssigned": false, + "title": "Create educational & technical video explaining AsyncAPI's main features", + "author": "alequetzalli", + "resourcePath": "/asyncapi/community/issues/155", + "repo": "asyncapi/community", + "labels": [ + { + "name": "enhancement", + "color": "a2eeef" + } + ], + "score": 33.31225229491402 + }, + { + "id": "PR_kwDOB5hCo85gDiV-", "isPR": true, "isAssigned": false, - "title": "feat: youtube to anchor workflow", + "title": "feat: new script and ci for JSON Schema validation", "author": "AnimeshKumar923", - "resourcePath": "/asyncapi/community/pull/805", - "repo": "asyncapi/community", + "resourcePath": "/asyncapi/spec-json-schemas/pull/452", + "repo": "asyncapi/spec-json-schemas", "labels": [], - "score": 30.727680996170687 + "score": 25.55853839868403 + }, + { + "id": "MDU6SXNzdWU5OTMxODc5ODM=", + "isPR": false, + "isAssigned": false, + "title": "Proposal to allow defining schema format other than default one (AsyncAPI Schema)", + "author": "magicmatatjahu", + "resourcePath": "/asyncapi/spec/issues/622", + "repo": "asyncapi/spec", + "labels": [ + { + "name": "stale", + "color": "819cd3" + }, + { + "name": "💭 Strawman (RFC 0)", + "color": "C2E0C6" + } + ], + "score": 23.26114168868996 }, { "id": "I_kwDOBGu-184_rP6l", @@ -68,7 +88,7 @@ "color": "C2E0C6" } ], - "score": 21.538094156194408 + "score": 21.825268744943667 }, { "id": "I_kwDOGJ23c85V9C3c", @@ -87,86 +107,64 @@ "score": 20.102221212448114 }, { - "id": "I_kwDOBW5R_c5BIl5P", + "id": "MDU6SXNzdWUzNjkwNDExMDc=", "isPR": false, - "isAssigned": true, - "title": "Add new page for collecting user testing participants", - "author": "mcturco", - "resourcePath": "/asyncapi/website/issues/529", - "repo": "asyncapi/website", + "isAssigned": false, + "title": "Support request/reply pattern", + "author": "adrianhopebailie", + "resourcePath": "/asyncapi/spec/issues/94", + "repo": "asyncapi/spec", "labels": [ { - "name": "enhancement", - "color": "84b6eb" + "name": "keep-open", + "color": "fce250" } ], - "score": 18.953522857451077 + "score": 20.070109582694446 }, { - "id": "PR_kwDOBW5R_c5VAjCE", - "isPR": true, + "id": "I_kwDOBW5R_c5BIl5P", + "isPR": false, "isAssigned": true, - "title": "docs: structure of a AsyncAPI document", - "author": "TRohit20", - "resourcePath": "/asyncapi/website/pull/1922", + "title": "Add new page for collecting user testing participants", + "author": "mcturco", + "resourcePath": "/asyncapi/website/issues/529", "repo": "asyncapi/website", "labels": [ { - "name": "📑 docs", - "color": "E50E99" - }, - { - "name": "area/docs", - "color": "e50e99" - }, - { - "name": "gsod", - "color": "7B5DB8" + "name": "enhancement", + "color": "84b6eb" } ], - "score": 17.517649913704783 + "score": 19.527872034949596 }, { - "id": "I_kwDOCVQpZM5M_dcV", - "isPR": false, - "isAssigned": true, - "title": "DocsUI: Messages Object output", - "author": "mcturco", - "resourcePath": "/asyncapi/asyncapi-react/issues/618", - "repo": "asyncapi/asyncapi-react", - "labels": [], - "score": 16.36895155870775 - }, - { - "id": "I_kwDODou01c5E_LV0", + "id": "I_kwDOE8Qh385nTCST", "isPR": false, "isAssigned": false, - "title": "Create onboarding for features of Studio", - "author": "mcturco", - "resourcePath": "/asyncapi/studio/issues/284", - "repo": "asyncapi/studio", + "title": "Improve layout of playground", + "author": "jonaslagoni", + "resourcePath": "/asyncapi/modelina/issues/1346", + "repo": "asyncapi/modelina", "labels": [ { "name": "enhancement", "color": "a2eeef" }, { - "name": "stale", - "color": "ededed" + "name": "good first issue", + "color": "7057ff" + }, + { + "name": "area/design", + "color": "0d67d3" + }, + { + "name": "website", + "color": "57A793" } ], - "score": 15.794602381209232 - }, - { - "id": "PR_kwDOFDnrNc5RUbi_", - "isPR": true, - "isAssigned": false, - "title": "fix: help command", - "author": "sambhavgupta0705", - "resourcePath": "/asyncapi/cli/pull/593", - "repo": "asyncapi/cli", - "labels": [], - "score": 15.220253203710714 + "score": 18.37917367995256 }, { "id": "PR_kwDOFLhIt85bqKL8", @@ -177,22 +175,33 @@ "resourcePath": "/asyncapi/community/pull/897", "repo": "asyncapi/community", "labels": [], - "score": 14.645904026212197 + "score": 16.65612614745701 + }, + { + "id": "MDU6SXNzdWUxMjMwODQwMDM4", + "isPR": false, + "isAssigned": false, + "title": "Usages of allOf within message payload could be flattened", + "author": "jamescrowley", + "resourcePath": "/asyncapi/asyncapi-react/issues/596", + "repo": "asyncapi/asyncapi-react", + "labels": [], + "score": 14.933078614961456 } ], "goodFirstIssues": [ { - "id": "I_kwDOCxglSM513Nta", - "title": "Remove messageId from v3 conversion", + "id": "I_kwDOBGu-1853mU6h", + "title": "Fix description of Operation Trait object", "isAssigned": false, - "resourcePath": "/asyncapi/converter-js/issues/201", - "repo": "asyncapi/converter-js", - "author": "jonaslagoni", - "area": "typescript", + "resourcePath": "/asyncapi/spec/issues/994", + "repo": "asyncapi/spec", + "author": "smoya", + "area": "Unknown", "labels": [ { - "name": "enhancement", - "color": "a2eeef" + "name": "🤷‍♀️ Ambiguity", + "color": "286AFC" } ] }, @@ -212,36 +221,32 @@ ] }, { - "id": "I_kwDODwv8N851VGrF", - "title": "Unhandled Runtime Error", + "id": "I_kwDOCoBobc5zovn3", + "title": "Parser do not validate if channel that is referenced in reply with location has `null` in address", "isAssigned": false, - "resourcePath": "/asyncapi/conference-website/issues/230", - "repo": "asyncapi/conference-website", - "author": "PUNEET-EMM", - "area": "Unknown", + "resourcePath": "/asyncapi/parser-js/issues/876", + "repo": "asyncapi/parser-js", + "author": "derberg", + "area": "typescript", "labels": [ { "name": "bug", "color": "d73a4a" - }, - { - "name": "Hacktoberfest", - "color": "FF8AE2" } ] }, { - "id": "I_kwDOFi_gUM51UQ-5", - "title": "Show a warning if glee can't process a received message", + "id": "I_kwDOCoBobc5zosuk", + "title": "Parser do not validate and throw error when `parameters` are provided but address is null", "isAssigned": false, - "resourcePath": "/asyncapi/glee/issues/558", - "repo": "asyncapi/glee", - "author": "KhudaDad414", + "resourcePath": "/asyncapi/parser-js/issues/875", + "repo": "asyncapi/parser-js", + "author": "derberg", "area": "typescript", "labels": [ { - "name": "enhancement", - "color": "a2eeef" + "name": "bug", + "color": "d73a4a" } ] }, @@ -358,25 +363,6 @@ } ] }, - { - "id": "I_kwDODwv8N85yZpkH", - "title": "Venue sub menu doesn't close", - "isAssigned": false, - "resourcePath": "/asyncapi/conference-website/issues/205", - "repo": "asyncapi/conference-website", - "author": "AceTheCreator", - "area": "Unknown", - "labels": [ - { - "name": "bug", - "color": "d73a4a" - }, - { - "name": "Hacktoberfest", - "color": "FF8AE2" - } - ] - }, { "id": "I_kwDODwv8N85yTwat", "title": "venues addresses to be clickable links that take you you google map location", @@ -396,21 +382,6 @@ } ] }, - { - "id": "I_kwDODwv8N85xwvMi", - "title": "Update `Get Free Tickets` on main page to link to proper google form", - "isAssigned": false, - "resourcePath": "/asyncapi/conference-website/issues/198", - "repo": "asyncapi/conference-website", - "author": "derberg", - "area": "Unknown", - "labels": [ - { - "name": "Hacktoberfest", - "color": "FF8AE2" - } - ] - }, { "id": "I_kwDODtTERs5wDOAH", "title": "Support decimal min and max", @@ -581,36 +552,6 @@ } ] }, - { - "id": "I_kwDOBW5R_c5qChBD", - "title": "[📑 Docs]: Adapt message validation guide for v3", - "isAssigned": true, - "resourcePath": "/asyncapi/website/issues/1865", - "repo": "asyncapi/website", - "author": "jonaslagoni", - "area": "docs", - "labels": [ - { - "name": "📑 docs", - "color": "E50E99" - } - ] - }, - { - "id": "I_kwDOBW5R_c5qCfY8", - "title": "[📑 Docs]: Adapt Validate AsyncAPI documents guide for v3", - "isAssigned": true, - "resourcePath": "/asyncapi/website/issues/1864", - "repo": "asyncapi/website", - "author": "jonaslagoni", - "area": "docs", - "labels": [ - { - "name": "📑 docs", - "color": "E50E99" - } - ] - }, { "id": "I_kwDOBW5R_c5qCdE5", "title": "[📑 Docs]: Adapt Streetlights - Interactive tutorial for v3", @@ -630,96 +571,6 @@ } ] }, - { - "id": "I_kwDOBW5R_c5qCcei", - "title": "[📑 Docs]: Adapt studio document validation tutorial for v3", - "isAssigned": true, - "resourcePath": "/asyncapi/website/issues/1862", - "repo": "asyncapi/website", - "author": "jonaslagoni", - "area": "docs", - "labels": [ - { - "name": "📑 docs", - "color": "E50E99" - } - ] - }, - { - "id": "I_kwDOBW5R_c5qCbgt", - "title": "[📑 Docs]: Adapt Create AsyncAPI document tutorial for v3", - "isAssigned": true, - "resourcePath": "/asyncapi/website/issues/1861", - "repo": "asyncapi/website", - "author": "jonaslagoni", - "area": "docs", - "labels": [ - { - "name": "📑 docs", - "color": "E50E99" - } - ] - }, - { - "id": "I_kwDOBW5R_c5qCX8o", - "title": "[📑 Docs]: Adapt Server Security tutorial for v3", - "isAssigned": true, - "resourcePath": "/asyncapi/website/issues/1860", - "repo": "asyncapi/website", - "author": "jonaslagoni", - "area": "docs", - "labels": [ - { - "name": "📑 docs", - "color": "E50E99" - } - ] - }, - { - "id": "I_kwDOBW5R_c5qCUxQ", - "title": "[📑 Docs]: Adapt Servers tutorial for v3", - "isAssigned": true, - "resourcePath": "/asyncapi/website/issues/1859", - "repo": "asyncapi/website", - "author": "jonaslagoni", - "area": "docs", - "labels": [ - { - "name": "📑 docs", - "color": "E50E99" - } - ] - }, - { - "id": "I_kwDOBW5R_c5qCQYN", - "title": "[📑 Docs]: Adapt AsyncAPI Documents tutorial for v3", - "isAssigned": true, - "resourcePath": "/asyncapi/website/issues/1858", - "repo": "asyncapi/website", - "author": "jonaslagoni", - "area": "docs", - "labels": [ - { - "name": "📑 docs", - "color": "E50E99" - } - ] - }, - { - "id": "I_kwDOBW5R_c5qCNJX", - "title": "[📑 Docs]: Adapt hello world tutorial for v3", - "isAssigned": true, - "resourcePath": "/asyncapi/website/issues/1857", - "repo": "asyncapi/website", - "author": "jonaslagoni", - "area": "docs", - "labels": [ - { - "name": "📑 docs", - "color": "E50E99" - } - ] - }, { "id": "I_kwDOBW5R_c5qCLdo", "title": "[📑 Docs]: Adapt coming from OpenAPI tutorial for v3", @@ -735,16 +586,6 @@ } ] }, - { - "id": "I_kwDOBW5R_c5qCG1z", - "title": "[📑 Docs]: Adapt github action tooling page for v3", - "isAssigned": true, - "resourcePath": "/asyncapi/website/issues/1854", - "repo": "asyncapi/website", - "author": "jonaslagoni", - "area": "Unknown", - "labels": [] - }, { "id": "I_kwDOFLhIt85o9dDJ", "title": "Add 2023 mentorship directory", diff --git a/package-lock.json b/package-lock.json index 2ae4706e352..b1873089983 100644 --- a/package-lock.json +++ b/package-lock.json @@ -27,7 +27,7 @@ "ajv": "^8.11.0", "ajv-formats": "^2.1.1", "autoprefixer": "^10.4.7", - "axios": "^0.27.2", + "axios": "^1.6.0", "clsx": "^1.1.1", "cssnano": "^5.1.12", "dotenv": "^8.2.0", @@ -672,10 +672,10 @@ } } }, - "node_modules/@fastify/busboy": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/@fastify/busboy/-/busboy-2.0.0.tgz", - "integrity": "sha512-JUFJad5lv7jxj926GPgymrWQxxjPYuJNiNjNMzqT+HiuP6Vl3dk5xzG+8sTX96np0ZAluvaMzPsjhHZ5rNuNQQ==", + "node_modules/@fastify/accept-negotiator": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@fastify/accept-negotiator/-/accept-negotiator-1.1.0.tgz", + "integrity": "sha512-OIHZrb2ImZ7XG85HXOONLcJWGosv7sIvM2ifAPQVhg9Lv7qdmMBNVaai4QTdyuaqbKM5eO6sLSQOYI7wEQeCJQ==", "dev": true, "engines": { "node": ">=14" @@ -1549,21 +1549,34 @@ } }, "node_modules/@netlify/ipx": { - "version": "1.4.0", - "resolved": "https://registry.npmjs.org/@netlify/ipx/-/ipx-1.4.0.tgz", - "integrity": "sha512-Ibqg1W41EVMHNT/W6JSDUyxjhcxsbEL9vL9ZaNjn9tVKnDYxJ8JqRTwSbzfns+K+M3FLqoC4PLW32qW+vT1pKQ==", + "version": "1.4.6", + "resolved": "https://registry.npmjs.org/@netlify/ipx/-/ipx-1.4.6.tgz", + "integrity": "sha512-rnKR2LXhtnflitPX9CQIv+XSrNlYIqGsV54xrXifhbtHHjCjCw/lixsi8qwAXqEIgZBC9b4Y7prhHqRtC4oIjw==", "dev": true, "dependencies": { - "@netlify/functions": "^1.4.0", + "@netlify/functions": "^2.4.0", "etag": "^1.8.1", "fs-extra": "^11.0.0", - "ipx": "^0.9.11", + "ipx": "^1.3.1", "micromatch": "^4.0.5", - "mkdirp": "^1.0.4", + "mkdirp": "^3.0.0", "murmurhash": "^2.0.0", "node-fetch": "^2.0.0", "ufo": "^1.0.0", - "unstorage": "^1.0.0" + "unstorage": "1.9.0" + } + }, + "node_modules/@netlify/ipx/node_modules/@netlify/functions": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/@netlify/functions/-/functions-2.4.0.tgz", + "integrity": "sha512-dIqhdj5u4Lu/8qbYwtYpn8NfvIyPHbSTV2lAP4ocL+iwC9As06AXT0wa/xOpO2vRWJa0IMxdZaqCPnkyHlHiyg==", + "dev": true, + "dependencies": { + "@netlify/serverless-functions-api": "1.11.0", + "is-promise": "^4.0.0" + }, + "engines": { + "node": ">=14.0.0" } }, "node_modules/@netlify/ipx/node_modules/fs-extra": { @@ -1580,6 +1593,15 @@ "node": ">=14.14" } }, + "node_modules/@netlify/node-cookies": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/@netlify/node-cookies/-/node-cookies-0.1.0.tgz", + "integrity": "sha512-OAs1xG+FfLX0LoRASpqzVntVV/RpYkgpI0VrUnw2u0Q1qiZUzcPffxRK8HF3gc4GjuhG5ahOEMJ9bswBiZPq0g==", + "dev": true, + "engines": { + "node": "^14.16.0 || >=16.0.0" + } + }, "node_modules/@netlify/plugin-nextjs": { "version": "4.37.2", "resolved": "https://registry.npmjs.org/@netlify/plugin-nextjs/-/plugin-nextjs-4.37.2.tgz", @@ -1754,6 +1776,19 @@ "node": ">=8" } }, + "node_modules/@netlify/serverless-functions-api": { + "version": "1.11.0", + "resolved": "https://registry.npmjs.org/@netlify/serverless-functions-api/-/serverless-functions-api-1.11.0.tgz", + "integrity": "sha512-3splAsr2CekL7VTwgo6yTvzD2+f269/s+TJafYazonqMNNo31yzvFxD5HpLtni4DNE1ppymVKZ4X/rLN3yl0vQ==", + "dev": true, + "dependencies": { + "@netlify/node-cookies": "^0.1.0", + "urlpattern-polyfill": "8.0.2" + }, + "engines": { + "node": "^14.18.0 || >=16.0.0" + } + }, "node_modules/@next/env": { "version": "12.3.1", "resolved": "https://registry.npmjs.org/@next/env/-/env-12.3.1.tgz", @@ -2047,6 +2082,307 @@ "@octokit/openapi-types": "^11.2.0" } }, + "node_modules/@parcel/watcher": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher/-/watcher-2.3.0.tgz", + "integrity": "sha512-pW7QaFiL11O0BphO+bq3MgqeX/INAk9jgBldVDYjlQPO4VddoZnF22TcF9onMhnLVHuNqBJeRf+Fj7eezi/+rQ==", + "dev": true, + "hasInstallScript": true, + "dependencies": { + "detect-libc": "^1.0.3", + "is-glob": "^4.0.3", + "micromatch": "^4.0.5", + "node-addon-api": "^7.0.0" + }, + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + }, + "optionalDependencies": { + "@parcel/watcher-android-arm64": "2.3.0", + "@parcel/watcher-darwin-arm64": "2.3.0", + "@parcel/watcher-darwin-x64": "2.3.0", + "@parcel/watcher-freebsd-x64": "2.3.0", + "@parcel/watcher-linux-arm-glibc": "2.3.0", + "@parcel/watcher-linux-arm64-glibc": "2.3.0", + "@parcel/watcher-linux-arm64-musl": "2.3.0", + "@parcel/watcher-linux-x64-glibc": "2.3.0", + "@parcel/watcher-linux-x64-musl": "2.3.0", + "@parcel/watcher-win32-arm64": "2.3.0", + "@parcel/watcher-win32-ia32": "2.3.0", + "@parcel/watcher-win32-x64": "2.3.0" + } + }, + "node_modules/@parcel/watcher-android-arm64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-android-arm64/-/watcher-android-arm64-2.3.0.tgz", + "integrity": "sha512-f4o9eA3dgk0XRT3XhB0UWpWpLnKgrh1IwNJKJ7UJek7eTYccQ8LR7XUWFKqw6aEq5KUNlCcGvSzKqSX/vtWVVA==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-darwin-arm64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-darwin-arm64/-/watcher-darwin-arm64-2.3.0.tgz", + "integrity": "sha512-mKY+oijI4ahBMc/GygVGvEdOq0L4DxhYgwQqYAz/7yPzuGi79oXrZG52WdpGA1wLBPrYb0T8uBaGFo7I6rvSKw==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-darwin-x64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-darwin-x64/-/watcher-darwin-x64-2.3.0.tgz", + "integrity": "sha512-20oBj8LcEOnLE3mgpy6zuOq8AplPu9NcSSSfyVKgfOhNAc4eF4ob3ldj0xWjGGbOF7Dcy1Tvm6ytvgdjlfUeow==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-freebsd-x64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-freebsd-x64/-/watcher-freebsd-x64-2.3.0.tgz", + "integrity": "sha512-7LftKlaHunueAEiojhCn+Ef2CTXWsLgTl4hq0pkhkTBFI3ssj2bJXmH2L67mKpiAD5dz66JYk4zS66qzdnIOgw==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-linux-arm-glibc": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-arm-glibc/-/watcher-linux-arm-glibc-2.3.0.tgz", + "integrity": "sha512-1apPw5cD2xBv1XIHPUlq0cO6iAaEUQ3BcY0ysSyD9Kuyw4MoWm1DV+W9mneWI+1g6OeP6dhikiFE6BlU+AToTQ==", + "cpu": [ + "arm" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-linux-arm64-glibc": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-arm64-glibc/-/watcher-linux-arm64-glibc-2.3.0.tgz", + "integrity": "sha512-mQ0gBSQEiq1k/MMkgcSB0Ic47UORZBmWoAWlMrTW6nbAGoLZP+h7AtUM7H3oDu34TBFFvjy4JCGP43JlylkTQA==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-linux-arm64-musl": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-arm64-musl/-/watcher-linux-arm64-musl-2.3.0.tgz", + "integrity": "sha512-LXZAExpepJew0Gp8ZkJ+xDZaTQjLHv48h0p0Vw2VMFQ8A+RKrAvpFuPVCVwKJCr5SE+zvaG+Etg56qXvTDIedw==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-linux-x64-glibc": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-x64-glibc/-/watcher-linux-x64-glibc-2.3.0.tgz", + "integrity": "sha512-P7Wo91lKSeSgMTtG7CnBS6WrA5otr1K7shhSjKHNePVmfBHDoAOHYRXgUmhiNfbcGk0uMCHVcdbfxtuiZCHVow==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-linux-x64-musl": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-x64-musl/-/watcher-linux-x64-musl-2.3.0.tgz", + "integrity": "sha512-+kiRE1JIq8QdxzwoYY+wzBs9YbJ34guBweTK8nlzLKimn5EQ2b2FSC+tAOpq302BuIMjyuUGvBiUhEcLIGMQ5g==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-wasm": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-wasm/-/watcher-wasm-2.3.0.tgz", + "integrity": "sha512-ejBAX8H0ZGsD8lSICDNyMbSEtPMWgDL0WFCt/0z7hyf5v8Imz4rAM8xY379mBsECkq/Wdqa5WEDLqtjZ+6NxfA==", + "bundleDependencies": [ + "napi-wasm" + ], + "dev": true, + "dependencies": { + "is-glob": "^4.0.3", + "micromatch": "^4.0.5", + "napi-wasm": "^1.1.0" + }, + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-wasm/node_modules/napi-wasm": { + "version": "1.1.0", + "dev": true, + "inBundle": true, + "license": "MIT" + }, + "node_modules/@parcel/watcher-win32-arm64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-win32-arm64/-/watcher-win32-arm64-2.3.0.tgz", + "integrity": "sha512-35gXCnaz1AqIXpG42evcoP2+sNL62gZTMZne3IackM+6QlfMcJLy3DrjuL6Iks7Czpd3j4xRBzez3ADCj1l7Aw==", + "cpu": [ + "arm64" + ], + "dev": true, + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-win32-ia32": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-win32-ia32/-/watcher-win32-ia32-2.3.0.tgz", + "integrity": "sha512-FJS/IBQHhRpZ6PiCjFt1UAcPr0YmCLHRbTc00IBTrelEjlmmgIVLeOx4MSXzx2HFEy5Jo5YdhGpxCuqCyDJ5ow==", + "cpu": [ + "ia32" + ], + "dev": true, + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/@parcel/watcher-win32-x64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-win32-x64/-/watcher-win32-x64-2.3.0.tgz", + "integrity": "sha512-dLx+0XRdMnVI62kU3wbXvbIRhLck4aE28bIGKbRGS7BJNt54IIj9+c/Dkqb+7DJEbHUZAX1bwaoM8PqVlHJmCA==", + "cpu": [ + "x64" + ], + "dev": true, + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">= 10.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, "node_modules/@slack/logger": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/@slack/logger/-/logger-3.0.0.tgz", @@ -2090,6 +2426,28 @@ "npm": ">= 6.12.0" } }, + "node_modules/@slack/web-api/node_modules/axios": { + "version": "0.27.2", + "resolved": "https://registry.npmjs.org/axios/-/axios-0.27.2.tgz", + "integrity": "sha512-t+yRIyySRTp/wua5xEr+z1q60QmLq8ABsS5O9Me1AsE5dfKqgnCFzwiCZZ/cGNd1lq4/7akDWMxdhVlucjmnOQ==", + "dependencies": { + "follow-redirects": "^1.14.9", + "form-data": "^4.0.0" + } + }, + "node_modules/@slack/web-api/node_modules/axios/node_modules/form-data": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.0.tgz", + "integrity": "sha512-ETEklSGi5t0QMZuiXoA/Q6vcnxcLQP5vdugSpuAyi6SVGi2clPPp+xgEhuMaHC+zGgn31Kd235W35f7Hykkaww==", + "dependencies": { + "asynckit": "^0.4.0", + "combined-stream": "^1.0.8", + "mime-types": "^2.1.12" + }, + "engines": { + "node": ">= 6" + } + }, "node_modules/@slack/web-api/node_modules/form-data": { "version": "2.5.1", "resolved": "https://registry.npmjs.org/form-data/-/form-data-2.5.1.tgz", @@ -2668,14 +3026,26 @@ "dev": true }, "node_modules/axios": { - "version": "0.27.2", - "resolved": "https://registry.npmjs.org/axios/-/axios-0.27.2.tgz", - "integrity": "sha512-t+yRIyySRTp/wua5xEr+z1q60QmLq8ABsS5O9Me1AsE5dfKqgnCFzwiCZZ/cGNd1lq4/7akDWMxdhVlucjmnOQ==", + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/axios/-/axios-1.6.0.tgz", + "integrity": "sha512-EZ1DYihju9pwVB+jg67ogm+Tmqc6JmhamRN6I4Zt8DfZu5lbcQGw3ozH9lFejSJgs/ibaef3A9PMXPLeefFGJg==", "dependencies": { - "follow-redirects": "^1.14.9", - "form-data": "^4.0.0" + "follow-redirects": "^1.15.0", + "form-data": "^4.0.0", + "proxy-from-env": "^1.1.0" } }, + "node_modules/axios/node_modules/proxy-from-env": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz", + "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==" + }, + "node_modules/b4a": { + "version": "1.6.4", + "resolved": "https://registry.npmjs.org/b4a/-/b4a-1.6.4.tgz", + "integrity": "sha512-fpWrvyVHEKyeEvbKZTVOeZF3VSKKWtJxFIxX/jaVPf+cLbGUSitjb49pHLqPV2BUNNZ0LcoeEGfE/YCpyDYHIw==", + "dev": true + }, "node_modules/babel-code-frame": { "version": "6.26.0", "resolved": "https://registry.npmjs.org/babel-code-frame/-/babel-code-frame-6.26.0.tgz", @@ -3156,6 +3526,15 @@ "node": ">=8" } }, + "node_modules/citty": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/citty/-/citty-0.1.4.tgz", + "integrity": "sha512-Q3bK1huLxzQrvj7hImJ7Z1vKYJRPQCDnd0EjXfHMidcjecGOMuLrmuQmtWmFkuKLcMThlGh1yCKG8IEc6VeNXQ==", + "dev": true, + "dependencies": { + "consola": "^3.2.3" + } + }, "node_modules/classnames": { "version": "2.2.6", "resolved": "https://registry.npmjs.org/classnames/-/classnames-2.2.6.tgz", @@ -3518,10 +3897,13 @@ "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==" }, "node_modules/consola": { - "version": "2.15.3", - "resolved": "https://registry.npmjs.org/consola/-/consola-2.15.3.tgz", - "integrity": "sha512-9vAdYbHj6x2fLKC4+oPH0kFzY/orMZyG2Aj+kNylHxKGJ/Ed4dpNyAQYwJOdqO4zdM7XpVHmyejQDcQHrnuXbw==", - "dev": true + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/consola/-/consola-3.2.3.tgz", + "integrity": "sha512-I5qxpzLv+sJhTVEoLYNcTW+bThDCPsit0vLNKShZx6rLtpilNpmmeTPaeqJb9ZE9dV3DGaeby6Vuhrw38WjeyQ==", + "dev": true, + "engines": { + "node": "^14.18.0 || >=16.10.0" + } }, "node_modules/convert-source-map": { "version": "1.9.0", @@ -4488,9 +4870,9 @@ "integrity": "sha512-Y2caI5+ZwS5c3RiNDJ6u53VhQHv+hHKwhkI1iHvceKUHw9Df6EK2zRLfjejRgMuCuxK7PfSWIMwWecceVvThjQ==" }, "node_modules/defu": { - "version": "6.1.2", - "resolved": "https://registry.npmjs.org/defu/-/defu-6.1.2.tgz", - "integrity": "sha512-+uO4+qr7msjNNWKYPHqN/3+Dx3NFkmIzayk2L1MyZQlvgZb/J1A0fo410dpKrN2SnqFjt8n4JL8fDJE0wIgjFQ==", + "version": "6.1.3", + "resolved": "https://registry.npmjs.org/defu/-/defu-6.1.3.tgz", + "integrity": "sha512-Vy2wmG3NTkmHNg/kzpuvHhkqeIx3ODWqasgCRbKtbXEN0G+HpEEv9BtJLp7ZG1CZloFaC41Ah3ZFbq7aqCqMeQ==", "dev": true }, "node_modules/delaunator": { @@ -4556,12 +4938,15 @@ } }, "node_modules/detect-libc": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.1.tgz", - "integrity": "sha512-463v3ZeIrcWtdgIg6vI6XUncguvr2TnGl4SzDXinkt9mSLpBJKXT3mW6xT3VQdDN11+WVs29pgvivTc4Lp8v+w==", + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-1.0.3.tgz", + "integrity": "sha512-pGjwhsmsp4kL2RTz08wcOlGN83otlqHeD/Z5T8GXZB+/YcpQ/dgo+lbU8ZsGxV0HIvqqxo9l7mqYwyYMD9bKDg==", "dev": true, + "bin": { + "detect-libc": "bin/detect-libc.js" + }, "engines": { - "node": ">=8" + "node": ">=0.10" } }, "node_modules/detective": { @@ -5024,6 +5409,12 @@ "integrity": "sha512-NCe8qxnZFARSHGztGMZOO/PC1qa5MIFB5Hp66WdzbCRAz8U8US3bx1UTgLS49efBQPcUtO9gf5oVEY8o7y/7Kg==", "dev": true }, + "node_modules/fast-fifo": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/fast-fifo/-/fast-fifo-1.3.2.tgz", + "integrity": "sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ==", + "dev": true + }, "node_modules/fast-glob": { "version": "3.2.12", "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.12.tgz", @@ -5211,12 +5602,6 @@ "node": ">=10" } }, - "node_modules/fs-memo": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/fs-memo/-/fs-memo-1.2.0.tgz", - "integrity": "sha512-YEexkCpL4j03jn5SxaMHqcO6IuWuqm8JFUYhyCep7Ao89JIYmB8xoKhK7zXXJ9cCaNXpyNH5L3QtAmoxjoHW2w==", - "dev": true - }, "node_modules/fs.realpath": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", @@ -5301,13 +5686,10 @@ } }, "node_modules/get-port-please": { - "version": "2.6.1", - "resolved": "https://registry.npmjs.org/get-port-please/-/get-port-please-2.6.1.tgz", - "integrity": "sha512-4PDSrL6+cuMM1xs6w36ZIkaKzzE0xzfVBCfebHIJ3FE8iB9oic/ECwPw3iNiD4h1AoJ5XLLBhEviFAVrZsDC5A==", - "dev": true, - "dependencies": { - "fs-memo": "^1.2.0" - } + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/get-port-please/-/get-port-please-3.1.1.tgz", + "integrity": "sha512-3UBAyM3u4ZBVYDsxOQfJDxEa6XTbpBDrOjp4mf7ExFRt5BKs/QywQQiJsh2B+hxcZLSapWqCRvElUe8DnKcFHA==", + "dev": true }, "node_modules/get-stream": { "version": "5.2.0", @@ -5534,20 +5916,27 @@ } }, "node_modules/h3": { - "version": "1.6.6", - "resolved": "https://registry.npmjs.org/h3/-/h3-1.6.6.tgz", - "integrity": "sha512-DWu2s11OuuO9suEkX99dXaJoxd1RgPXiM4iDmLdrhGV63GLoav13f3Kdd5/Rw7xNKzhzn2+F2dleQjG66SnMPQ==", + "version": "1.8.2", + "resolved": "https://registry.npmjs.org/h3/-/h3-1.8.2.tgz", + "integrity": "sha512-1Ca0orJJlCaiFY68BvzQtP2lKLk46kcLAxVM8JgYbtm2cUg6IY7pjpYgWMwUvDO9QI30N5JAukOKoT8KD3Q0PQ==", "dev": true, "dependencies": { "cookie-es": "^1.0.0", "defu": "^6.1.2", - "destr": "^1.2.2", - "iron-webcrypto": "^0.7.0", - "radix3": "^1.0.1", - "ufo": "^1.1.2", - "uncrypto": "^0.1.2" + "destr": "^2.0.1", + "iron-webcrypto": "^0.10.1", + "radix3": "^1.1.0", + "ufo": "^1.3.0", + "uncrypto": "^0.1.3", + "unenv": "^1.7.4" } }, + "node_modules/h3/node_modules/destr": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/destr/-/destr-2.0.2.tgz", + "integrity": "sha512-65AlobnZMiCET00KaFFjUefxDX0khFA/E4myqZ7a6Sq1yZtR8+FVIvilVX66vF2uobSumxooYZChiRPCKNqhmg==", + "dev": true + }, "node_modules/has": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/has/-/has-1.0.3.tgz", @@ -6175,56 +6564,45 @@ "url": "https://opencollective.com/ioredis" } }, - "node_modules/ip-regex": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/ip-regex/-/ip-regex-5.0.0.tgz", - "integrity": "sha512-fOCG6lhoKKakwv+C6KdsOnGvgXnmgfmp0myi3bcNwj3qfwPAxRKWEuFhvEFF7ceYIz6+1jRZ+yguLFAmUNPEfw==", - "dev": true, - "engines": { - "node": "^12.20.0 || ^14.13.1 || >=16.0.0" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, "node_modules/ipx": { - "version": "0.9.11", - "resolved": "https://registry.npmjs.org/ipx/-/ipx-0.9.11.tgz", - "integrity": "sha512-/wsBt7hV8rvNR6O4kwgOUAhtm0F/M/mXaolXot/Bz7fdOD+W7i9OtWuoASWv1PFwwtOunhZGaoCx8BOpSdG2VQ==", + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/ipx/-/ipx-1.3.1.tgz", + "integrity": "sha512-hWRLXdMDOz2q81T2x9lowFtAGO3E5b2HtC8xOOBTrlnxygHNaVrZqJ5c1P3T7tDkC3oCocYRRz0VBffvJKeQlw==", "dev": true, "dependencies": { - "consola": "^2.15.3", - "defu": "^6.1.0", - "destr": "^1.1.1", + "@fastify/accept-negotiator": "^1.1.0", + "consola": "^3.2.3", + "defu": "^6.1.2", + "destr": "^2.0.1", "etag": "^1.8.1", "image-meta": "^0.1.1", - "listhen": "^0.2.15", - "ohmyfetch": "^0.4.18", - "pathe": "^0.3.5", - "sharp": "^0.30.7", - "ufo": "^0.8.5", + "listhen": "^1.5.5", + "node-fetch-native": "^1.4.0", + "pathe": "^1.1.1", + "sharp": "^0.32.6", + "ufo": "^1.3.1", "xss": "^1.0.14" }, "bin": { "ipx": "bin/ipx.mjs" } }, - "node_modules/ipx/node_modules/pathe": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/pathe/-/pathe-0.3.9.tgz", - "integrity": "sha512-6Y6s0vT112P3jD8dGfuS6r+lpa0qqNrLyHPOwvXMnyNTQaYiwgau2DP3aNDsR13xqtGj7rrPo+jFUATpU6/s+g==", + "node_modules/ipx/node_modules/destr": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/destr/-/destr-2.0.2.tgz", + "integrity": "sha512-65AlobnZMiCET00KaFFjUefxDX0khFA/E4myqZ7a6Sq1yZtR8+FVIvilVX66vF2uobSumxooYZChiRPCKNqhmg==", "dev": true }, - "node_modules/ipx/node_modules/ufo": { - "version": "0.8.6", - "resolved": "https://registry.npmjs.org/ufo/-/ufo-0.8.6.tgz", - "integrity": "sha512-fk6CmUgwKCfX79EzcDQQpSCMxrHstvbLswFChHS0Vump+kFkw7nJBfTZoC1j0bOGoY9I7R3n2DGek5ajbcYnOw==", + "node_modules/ipx/node_modules/pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", "dev": true }, "node_modules/iron-webcrypto": { - "version": "0.7.0", - "resolved": "https://registry.npmjs.org/iron-webcrypto/-/iron-webcrypto-0.7.0.tgz", - "integrity": "sha512-WkX32iTcwd79ZsWRPP5wq1Jq6XXfPwO783ZiUBY8uMw4/AByx5WvBmxvYGnpVt6AOVJ0F41Qo420r8lIneT9Wg==", + "version": "0.10.1", + "resolved": "https://registry.npmjs.org/iron-webcrypto/-/iron-webcrypto-0.10.1.tgz", + "integrity": "sha512-QGOS8MRMnj/UiOa+aMIgfyHcvkhqNUsUxb1XzskENvbo+rEfp6TOwqd1KPuDzXC4OnGHcMSVxDGRoilqB8ViqA==", "dev": true, "funding": { "url": "https://github.com/sponsors/brc-dd" @@ -6551,6 +6929,15 @@ "resolved": "https://registry.npmjs.org/jgexml/-/jgexml-0.4.4.tgz", "integrity": "sha512-j0AzSWT7LXy3s3i1cdv5NZxUtscocwiBxgOLiEBfitCehm8STdXVrcOlbAWsJFLCq1elZYpQlGqA9k8Z+n9iJA==" }, + "node_modules/jiti": { + "version": "1.21.0", + "resolved": "https://registry.npmjs.org/jiti/-/jiti-1.21.0.tgz", + "integrity": "sha512-gFqAIbuKyyso/3G2qhiO2OM6shY6EPP/R0+mkDbyspxKazh8BXDC5FiFsUjlczgdNz/vfra0da2y+aHrusLG/Q==", + "dev": true, + "bin": { + "jiti": "bin/jiti.js" + } + }, "node_modules/js-cookie": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/js-cookie/-/js-cookie-3.0.1.tgz", @@ -6634,6 +7021,12 @@ "node": ">=6" } }, + "node_modules/jsonc-parser": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz", + "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==", + "dev": true + }, "node_modules/jsonfile": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", @@ -6735,24 +7128,38 @@ } }, "node_modules/listhen": { - "version": "0.2.15", - "resolved": "https://registry.npmjs.org/listhen/-/listhen-0.2.15.tgz", - "integrity": "sha512-F/IWj/aJLeokHAIVY+l3JoWRUnbRaf2F0cr+Ybc1YyozMA/yP0C2nf3c0Oi7vAbFvtfiwfWWfP7bIrQc/u5L1A==", + "version": "1.5.5", + "resolved": "https://registry.npmjs.org/listhen/-/listhen-1.5.5.tgz", + "integrity": "sha512-LXe8Xlyh3gnxdv4tSjTjscD1vpr/2PRpzq8YIaMJgyKzRG8wdISlWVWnGThJfHnlJ6hmLt2wq1yeeix0TEbuoA==", "dev": true, "dependencies": { + "@parcel/watcher": "^2.3.0", + "@parcel/watcher-wasm": "2.3.0", + "citty": "^0.1.4", "clipboardy": "^3.0.0", - "colorette": "^2.0.19", - "defu": "^6.0.0", - "get-port-please": "^2.6.1", + "consola": "^3.2.3", + "defu": "^6.1.2", + "get-port-please": "^3.1.1", + "h3": "^1.8.1", "http-shutdown": "^1.2.2", - "selfsigned": "^2.0.1", - "ufo": "^0.8.5" + "jiti": "^1.20.0", + "mlly": "^1.4.2", + "node-forge": "^1.3.1", + "pathe": "^1.1.1", + "std-env": "^3.4.3", + "ufo": "^1.3.0", + "untun": "^0.1.2", + "uqr": "^0.1.2" + }, + "bin": { + "listen": "bin/listhen.mjs", + "listhen": "bin/listhen.mjs" } }, - "node_modules/listhen/node_modules/ufo": { - "version": "0.8.6", - "resolved": "https://registry.npmjs.org/ufo/-/ufo-0.8.6.tgz", - "integrity": "sha512-fk6CmUgwKCfX79EzcDQQpSCMxrHstvbLswFChHS0Vump+kFkw7nJBfTZoC1j0bOGoY9I7R3n2DGek5ajbcYnOw==", + "node_modules/listhen/node_modules/pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", "dev": true }, "node_modules/listr2": { @@ -8106,6 +8513,18 @@ "node": ">=8.6" } }, + "node_modules/mime": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/mime/-/mime-3.0.0.tgz", + "integrity": "sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A==", + "dev": true, + "bin": { + "mime": "cli.js" + }, + "engines": { + "node": ">=10.0.0" + } + }, "node_modules/mime-db": { "version": "1.52.0", "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz", @@ -8229,21 +8648,54 @@ "integrity": "sha1-TkMekrEalzFjaqH5yNHMvP2reN8=" }, "node_modules/mkdirp": { - "version": "1.0.4", - "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz", - "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==", + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-3.0.1.tgz", + "integrity": "sha512-+NsyUUAZDmo6YVHzL/stxSu3t9YS1iljliy3BSDrXJ/dkn1KYdmtZODGGjLcc9XLgVVpH4KshHB8XmZgMhaBXg==", "dev": true, "bin": { - "mkdirp": "bin/cmd.js" + "mkdirp": "dist/cjs/src/bin.js" }, "engines": { "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/mkdirp-classic": { + "version": "0.5.3", + "resolved": "https://registry.npmjs.org/mkdirp-classic/-/mkdirp-classic-0.5.3.tgz", + "integrity": "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==", + "dev": true + }, + "node_modules/mlly": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.4.2.tgz", + "integrity": "sha512-i/Ykufi2t1EZ6NaPLdfnZk2AX8cs0d+mTzVKuPfqPKPatxLApaBoxJQ9x1/uckXtrS/U5oisPMDkNs0yQTaBRg==", + "dev": true, + "dependencies": { + "acorn": "^8.10.0", + "pathe": "^1.1.1", + "pkg-types": "^1.0.3", + "ufo": "^1.3.0" + } + }, + "node_modules/mlly/node_modules/acorn": { + "version": "8.11.2", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.11.2.tgz", + "integrity": "sha512-nc0Axzp/0FILLEVsm4fNwLCwMttvhEI263QtVPQcbpfZZ3ts0hLsZGOpE6czNlid7CJ9MlyH8reXkpsf3YUY4w==", + "dev": true, + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" } }, - "node_modules/mkdirp-classic": { - "version": "0.5.3", - "resolved": "https://registry.npmjs.org/mkdirp-classic/-/mkdirp-classic-0.5.3.tgz", - "integrity": "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==", + "node_modules/mlly/node_modules/pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", "dev": true }, "node_modules/moize": { @@ -8454,9 +8906,9 @@ } }, "node_modules/node-abi": { - "version": "3.40.0", - "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.40.0.tgz", - "integrity": "sha512-zNy02qivjjRosswoYmPi8hIKJRr8MpQyeKT6qlcq/OnOgA3Rhoae+IYOqsM9V5+JnHWmxKnWOT2GxvtqdtOCXA==", + "version": "3.51.0", + "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.51.0.tgz", + "integrity": "sha512-SQkEP4hmNWjlniS5zdnfIXTk1x7Ome85RDzHlTbBtzE97Gfwz/Ipw4v/Ryk20DWIy3yCNVLVlGKApCnmvYoJbA==", "dev": true, "dependencies": { "semver": "^7.3.5" @@ -8466,9 +8918,9 @@ } }, "node_modules/node-addon-api": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-5.1.0.tgz", - "integrity": "sha512-eh0GgfEkpnoWDq+VY8OyvYhFEzBk6jIYbRKdIlyTiAXIVJ8PyBaKb0rp7oDtoddbdoHWhq8wwr+XZ81F1rpNdA==", + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.0.0.tgz", + "integrity": "sha512-vgbBJTS4m5/KkE16t5Ly0WW9hz46swAstv0hYYwMtbG7AznRhNyfLRe8HZAiWIpcHzoO7HxhLuBQj9rJ/Ho0ZA==", "dev": true }, "node_modules/node-fetch": { @@ -8491,9 +8943,9 @@ } }, "node_modules/node-fetch-native": { - "version": "0.1.8", - "resolved": "https://registry.npmjs.org/node-fetch-native/-/node-fetch-native-0.1.8.tgz", - "integrity": "sha512-ZNaury9r0NxaT2oL65GvdGDy+5PlSaHTovT6JV5tOW07k1TQmgC0olZETa4C9KZg0+6zBr99ctTYa3Utqj9P/Q==", + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/node-fetch-native/-/node-fetch-native-1.4.1.tgz", + "integrity": "sha512-NsXBU0UgBxo2rQLOeWNZqS3fvflWePMECr8CoSWoSTqCqGbVVsvl9vZu1HfQicYN0g5piV9Gh8RTEvo/uP752w==", "dev": true }, "node_modules/node-forge": { @@ -8609,38 +9061,20 @@ "integrity": "sha1-TkMekrEalzFjaqH5yNHMvP2reN8=" }, "node_modules/ofetch": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/ofetch/-/ofetch-1.0.1.tgz", - "integrity": "sha512-icBz2JYfEpt+wZz1FRoGcrMigjNKjzvufE26m9+yUiacRQRHwnNlGRPiDnW4op7WX/MR6aniwS8xw8jyVelF2g==", - "dev": true, - "dependencies": { - "destr": "^1.2.2", - "node-fetch-native": "^1.0.2", - "ufo": "^1.1.0" - } - }, - "node_modules/ofetch/node_modules/node-fetch-native": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/node-fetch-native/-/node-fetch-native-1.1.1.tgz", - "integrity": "sha512-9VvspTSUp2Sxbl+9vbZTlFGq9lHwE8GDVVekxx6YsNd1YH59sb3Ba8v3Y3cD8PkLNcileGGcA21PFjVl0jzDaw==", - "dev": true - }, - "node_modules/ohmyfetch": { - "version": "0.4.21", - "resolved": "https://registry.npmjs.org/ohmyfetch/-/ohmyfetch-0.4.21.tgz", - "integrity": "sha512-VG7f/JRvqvBOYvL0tHyEIEG7XHWm7OqIfAs6/HqwWwDfjiJ1g0huIpe5sFEmyb+7hpFa1EGNH2aERWR72tlClw==", + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/ofetch/-/ofetch-1.3.3.tgz", + "integrity": "sha512-s1ZCMmQWXy4b5K/TW9i/DtiN8Ku+xCiHcjQ6/J/nDdssirrQNOoB165Zu8EqLMA2lln1JUth9a0aW9Ap2ctrUg==", "dev": true, "dependencies": { - "destr": "^1.2.0", - "node-fetch-native": "^0.1.8", - "ufo": "^0.8.6", - "undici": "^5.12.0" + "destr": "^2.0.1", + "node-fetch-native": "^1.4.0", + "ufo": "^1.3.0" } }, - "node_modules/ohmyfetch/node_modules/ufo": { - "version": "0.8.6", - "resolved": "https://registry.npmjs.org/ufo/-/ufo-0.8.6.tgz", - "integrity": "sha512-fk6CmUgwKCfX79EzcDQQpSCMxrHstvbLswFChHS0Vump+kFkw7nJBfTZoC1j0bOGoY9I7R3n2DGek5ajbcYnOw==", + "node_modules/ofetch/node_modules/destr": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/destr/-/destr-2.0.2.tgz", + "integrity": "sha512-65AlobnZMiCET00KaFFjUefxDX0khFA/E4myqZ7a6Sq1yZtR8+FVIvilVX66vF2uobSumxooYZChiRPCKNqhmg==", "dev": true }, "node_modules/once": { @@ -9027,6 +9461,23 @@ "node": ">=0.10.0" } }, + "node_modules/pkg-types": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/pkg-types/-/pkg-types-1.0.3.tgz", + "integrity": "sha512-nN7pYi0AQqJnoLPC9eHFQ8AcyaixBUOwvqc5TDnIKCMEE6I0y8P7OKA7fPexsXGCGxQDl/cmrLAp26LhcwxZ4A==", + "dev": true, + "dependencies": { + "jsonc-parser": "^3.2.0", + "mlly": "^1.2.0", + "pathe": "^1.1.0" + } + }, + "node_modules/pkg-types/node_modules/pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", + "dev": true + }, "node_modules/point-in-polygon": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/point-in-polygon/-/point-in-polygon-1.1.0.tgz", @@ -9717,6 +10168,57 @@ "node": ">=10" } }, + "node_modules/prebuild-install/node_modules/detect-libc": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.2.tgz", + "integrity": "sha512-UX6sGumvvqSaXgdKGUsgZWqcUyIXZ/vZTrlRT/iobiKhGL0zL4d3osHj3uqllWJK+i+sixDS/3COVEOFbupFyw==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/prebuild-install/node_modules/readable-stream": { + "version": "3.6.2", + "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz", + "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==", + "dev": true, + "dependencies": { + "inherits": "^2.0.3", + "string_decoder": "^1.1.1", + "util-deprecate": "^1.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/prebuild-install/node_modules/tar-fs": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.1.tgz", + "integrity": "sha512-V0r2Y9scmbDRLCNex/+hYzvp/zyYjvFbHPNgVTKfQvVrb6guiE/fxP+XblDNR011utopbkex2nM4dHNV6GDsng==", + "dev": true, + "dependencies": { + "chownr": "^1.1.1", + "mkdirp-classic": "^0.5.2", + "pump": "^3.0.0", + "tar-stream": "^2.1.4" + } + }, + "node_modules/prebuild-install/node_modules/tar-stream": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz", + "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==", + "dev": true, + "dependencies": { + "bl": "^4.0.3", + "end-of-stream": "^1.4.1", + "fs-constants": "^1.0.0", + "inherits": "^2.0.3", + "readable-stream": "^3.1.1" + }, + "engines": { + "node": ">=6" + } + }, "node_modules/pretty-bytes": { "version": "5.6.0", "resolved": "https://registry.npmjs.org/pretty-bytes/-/pretty-bytes-5.6.0.tgz", @@ -9889,6 +10391,12 @@ } ] }, + "node_modules/queue-tick": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/queue-tick/-/queue-tick-1.0.1.tgz", + "integrity": "sha512-kJt5qhMxoszgU/62PLP1CJytzd2NKetjSRnyuj31fDd3Rlcz3fzlFdFLD1SItunPwyqEOkca6GbV612BWfaBag==", + "dev": true + }, "node_modules/quick-lru": { "version": "5.1.1", "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-5.1.1.tgz", @@ -9901,9 +10409,9 @@ } }, "node_modules/radix3": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/radix3/-/radix3-1.0.1.tgz", - "integrity": "sha512-y+AcwZ3HcUIGc9zGsNVf5+BY/LxL+z+4h4J3/pp8jxSmy1STaCocPS3qrj4tA5ehUSzqtqK+0Aygvz/r/8vy4g==", + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/radix3/-/radix3-1.1.0.tgz", + "integrity": "sha512-pNsHDxbGORSvuSScqNJ+3Km6QAVqk8CfsCBIEoDgpqLrkD2f3QM4I7d1ozJJ172OmIcoUcerZaNWqtLkRXTV3A==", "dev": true }, "node_modules/raf": { @@ -9964,15 +10472,6 @@ "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==", "dev": true }, - "node_modules/rc/node_modules/strip-json-comments": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz", - "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==", - "dev": true, - "engines": { - "node": ">=0.10.0" - } - }, "node_modules/react": { "version": "17.0.2", "resolved": "https://registry.npmjs.org/react/-/react-17.0.2.tgz", @@ -10637,18 +11136,6 @@ "integrity": "sha512-OwpTSOfy6xSs1+pwcNrv0RBMOzI39Lp3qQKUTPVVPRjCdNa5JH/oPRiqsesIskK8TVgmRiHwO4KXlV2Li9dANA==", "optional": true }, - "node_modules/selfsigned": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/selfsigned/-/selfsigned-2.1.1.tgz", - "integrity": "sha512-GSL3aowiF7wa/WtSFwnUrludWFoNhftq8bUkH9pkzjpN2XSPOAYEgg6e0sS9s0rZwgJzJiQRPU18A6clnoW5wQ==", - "dev": true, - "dependencies": { - "node-forge": "^1" - }, - "engines": { - "node": ">=10" - } - }, "node_modules/semver": { "version": "7.5.4", "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.4.tgz", @@ -10678,28 +11165,43 @@ "integrity": "sha1-KQy7Iy4waULX1+qbg3Mqt4VvgoU=" }, "node_modules/sharp": { - "version": "0.30.7", - "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.30.7.tgz", - "integrity": "sha512-G+MY2YW33jgflKPTXXptVO28HvNOo9G3j0MybYAHeEmby+QuD2U98dT6ueht9cv/XDqZspSpIhoSW+BAKJ7Hig==", + "version": "0.32.6", + "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.32.6.tgz", + "integrity": "sha512-KyLTWwgcR9Oe4d9HwCwNM2l7+J0dUQwn/yf7S0EnTtb0eVS4RxO0eUSvxPtzT4F3SY+C4K6fqdv/DO27sJ/v/w==", "dev": true, "hasInstallScript": true, "dependencies": { "color": "^4.2.3", - "detect-libc": "^2.0.1", - "node-addon-api": "^5.0.0", + "detect-libc": "^2.0.2", + "node-addon-api": "^6.1.0", "prebuild-install": "^7.1.1", - "semver": "^7.3.7", + "semver": "^7.5.4", "simple-get": "^4.0.1", - "tar-fs": "^2.1.1", + "tar-fs": "^3.0.4", "tunnel-agent": "^0.6.0" }, "engines": { - "node": ">=12.13.0" + "node": ">=14.15.0" }, "funding": { "url": "https://opencollective.com/libvips" } }, + "node_modules/sharp/node_modules/detect-libc": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.2.tgz", + "integrity": "sha512-UX6sGumvvqSaXgdKGUsgZWqcUyIXZ/vZTrlRT/iobiKhGL0zL4d3osHj3uqllWJK+i+sixDS/3COVEOFbupFyw==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/sharp/node_modules/node-addon-api": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-6.1.0.tgz", + "integrity": "sha512-+eawOlIgy680F0kBzPUNFhMZGtJ1YmqM6l4+Crf4IkImjYrO/mqPwRMh352g23uIaQKFItcQ64I7KMaJxHgAVA==", + "dev": true + }, "node_modules/shebang-command": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", @@ -10925,6 +11427,22 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/std-env": { + "version": "3.5.0", + "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.5.0.tgz", + "integrity": "sha512-JGUEaALvL0Mf6JCfYnJOTcobY+Nc7sG/TemDRBqCA0wEr4DER7zDchaaixTlmOxAjG1uRJmX82EQcxwTQTkqVA==", + "dev": true + }, + "node_modules/streamx": { + "version": "2.15.5", + "resolved": "https://registry.npmjs.org/streamx/-/streamx-2.15.5.tgz", + "integrity": "sha512-9thPGMkKC2GctCzyCUjME3yR03x2xNo0GPKGkRw2UMYN+gqWa9uqpyNWhmsNCutU5zHmkUum0LsCRQTXUgUCAg==", + "dev": true, + "dependencies": { + "fast-fifo": "^1.1.0", + "queue-tick": "^1.0.1" + } + }, "node_modules/string_decoder": { "version": "1.3.0", "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz", @@ -11009,6 +11527,15 @@ "node": ">=6" } }, + "node_modules/strip-json-comments": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz", + "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/style-to-object": { "version": "0.4.1", "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-0.4.1.tgz", @@ -11261,45 +11788,25 @@ } }, "node_modules/tar-fs": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.1.tgz", - "integrity": "sha512-V0r2Y9scmbDRLCNex/+hYzvp/zyYjvFbHPNgVTKfQvVrb6guiE/fxP+XblDNR011utopbkex2nM4dHNV6GDsng==", + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-3.0.4.tgz", + "integrity": "sha512-5AFQU8b9qLfZCX9zp2duONhPmZv0hGYiBPJsyUdqMjzq/mqVpy/rEUSeHk1+YitmxugaptgBh5oDGU3VsAJq4w==", "dev": true, "dependencies": { - "chownr": "^1.1.1", "mkdirp-classic": "^0.5.2", "pump": "^3.0.0", - "tar-stream": "^2.1.4" + "tar-stream": "^3.1.5" } }, "node_modules/tar-stream": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz", - "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==", - "dev": true, - "dependencies": { - "bl": "^4.0.3", - "end-of-stream": "^1.4.1", - "fs-constants": "^1.0.0", - "inherits": "^2.0.3", - "readable-stream": "^3.1.1" - }, - "engines": { - "node": ">=6" - } - }, - "node_modules/tar-stream/node_modules/readable-stream": { - "version": "3.6.2", - "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz", - "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==", + "version": "3.1.6", + "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-3.1.6.tgz", + "integrity": "sha512-B/UyjYwPpMBv+PaFSWAmtYjwdrlEaZQEhMIBFNC5oEG8lpiW8XjcSdmEaClj28ArfKScKHs2nshz3k2le6crsg==", "dev": true, "dependencies": { - "inherits": "^2.0.3", - "string_decoder": "^1.1.1", - "util-deprecate": "^1.0.1" - }, - "engines": { - "node": ">= 6" + "b4a": "^1.6.4", + "fast-fifo": "^1.2.0", + "streamx": "^2.15.0" } }, "node_modules/throttleit": { @@ -11497,29 +12004,36 @@ "integrity": "sha512-qLK/Xe9E2uzmYI3qLeOmI0tEOt+TBBQyUIAh4aAgU05FVYzeZrKUdkAZfBNVGRaHVgV0TDkdEngJSw/SyQchkQ==" }, "node_modules/ufo": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.1.2.tgz", - "integrity": "sha512-TrY6DsjTQQgyS3E3dBaOXf0TpPD8u9FVrVYmKVegJuFw51n/YB9XPt+U6ydzFG5ZIN7+DIjPbNmXoBj9esYhgQ==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.3.2.tgz", + "integrity": "sha512-o+ORpgGwaYQXgqGDwd+hkS4PuZ3QnmqMMxRuajK/a38L6fTpcE5GPIfrf+L/KemFzfUpeUQc1rRS1iDBozvnFA==", "dev": true }, "node_modules/uncrypto": { - "version": "0.1.2", - "resolved": "https://registry.npmjs.org/uncrypto/-/uncrypto-0.1.2.tgz", - "integrity": "sha512-kuZwRKV615lEw/Xx3Iz56FKk3nOeOVGaVmw0eg+x4Mne28lCotNFbBhDW7dEBCBKyKbRQiCadEZeNAFPVC5cgw==", + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/uncrypto/-/uncrypto-0.1.3.tgz", + "integrity": "sha512-Ql87qFHB3s/De2ClA9e0gsnS6zXG27SkTiSJwjCc9MebbfapQfuPzumMIUMi38ezPZVNFcHI9sUIepeQfw8J8Q==", "dev": true }, - "node_modules/undici": { - "version": "5.26.3", - "resolved": "https://registry.npmjs.org/undici/-/undici-5.26.3.tgz", - "integrity": "sha512-H7n2zmKEWgOllKkIUkLvFmsJQj062lSm3uA4EYApG8gLuiOM0/go9bIoC3HVaSnfg4xunowDE2i9p8drkXuvDw==", + "node_modules/unenv": { + "version": "1.7.4", + "resolved": "https://registry.npmjs.org/unenv/-/unenv-1.7.4.tgz", + "integrity": "sha512-fjYsXYi30It0YCQYqLOcT6fHfMXsBr2hw9XC7ycf8rTG7Xxpe3ZssiqUnD0khrjiZEmkBXWLwm42yCSCH46fMw==", "dev": true, "dependencies": { - "@fastify/busboy": "^2.0.0" - }, - "engines": { - "node": ">=14.0" + "consola": "^3.2.3", + "defu": "^6.1.2", + "mime": "^3.0.0", + "node-fetch-native": "^1.4.0", + "pathe": "^1.1.1" } }, + "node_modules/unenv/node_modules/pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", + "dev": true + }, "node_modules/unherit": { "version": "1.1.3", "resolved": "https://registry.npmjs.org/unherit/-/unherit-1.1.3.tgz", @@ -11708,33 +12222,35 @@ } }, "node_modules/unstorage": { - "version": "1.6.1", - "resolved": "https://registry.npmjs.org/unstorage/-/unstorage-1.6.1.tgz", - "integrity": "sha512-GUJzwbP5IStEGZy9/0peRqef5CY9icqApsSu8vxj13admjISyz1g5eYk2wPRBjmZhQ3DUMQ36q+zwTbe68khew==", + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/unstorage/-/unstorage-1.9.0.tgz", + "integrity": "sha512-VpD8ZEYc/le8DZCrny3bnqKE4ZjioQxBRnWE+j5sGNvziPjeDlaS1NaFFHzl/kkXaO3r7UaF8MGQrs14+1B4pQ==", "dev": true, "dependencies": { "anymatch": "^3.1.3", "chokidar": "^3.5.3", - "destr": "^1.2.2", - "h3": "^1.6.6", + "destr": "^2.0.1", + "h3": "^1.7.1", "ioredis": "^5.3.2", - "listhen": "^1.0.4", - "lru-cache": "^9.1.1", + "listhen": "^1.2.2", + "lru-cache": "^10.0.0", "mri": "^1.2.0", - "node-fetch-native": "^1.1.1", - "ofetch": "^1.0.1", - "ufo": "^1.1.2" + "node-fetch-native": "^1.2.0", + "ofetch": "^1.1.1", + "ufo": "^1.2.0" }, "peerDependencies": { "@azure/app-configuration": "^1.4.1", "@azure/cosmos": "^3.17.3", "@azure/data-tables": "^13.2.2", - "@azure/identity": "^3.2.2", + "@azure/identity": "^3.2.3", "@azure/keyvault-secrets": "^4.7.0", "@azure/storage-blob": "^12.14.0", - "@planetscale/database": "^1.7.0", - "@upstash/redis": "^1.20.6", - "@vercel/kv": "^0.2.1" + "@capacitor/preferences": "^5.0.0", + "@planetscale/database": "^1.8.0", + "@upstash/redis": "^1.22.0", + "@vercel/kv": "^0.2.2", + "idb-keyval": "^6.2.1" }, "peerDependenciesMeta": { "@azure/app-configuration": { @@ -11755,6 +12271,9 @@ "@azure/storage-blob": { "optional": true }, + "@capacitor/preferences": { + "optional": true + }, "@planetscale/database": { "optional": true }, @@ -11763,46 +12282,30 @@ }, "@vercel/kv": { "optional": true + }, + "idb-keyval": { + "optional": true } } }, - "node_modules/unstorage/node_modules/get-port-please": { - "version": "3.0.1", - "resolved": "https://registry.npmjs.org/get-port-please/-/get-port-please-3.0.1.tgz", - "integrity": "sha512-R5pcVO8Z1+pVDu8Ml3xaJCEkBiiy1VQN9za0YqH8GIi1nIqD4IzQhzY6dDzMRtdS1lyiGlucRzm8IN8wtLIXng==", + "node_modules/unstorage/node_modules/destr": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/destr/-/destr-2.0.2.tgz", + "integrity": "sha512-65AlobnZMiCET00KaFFjUefxDX0khFA/E4myqZ7a6Sq1yZtR8+FVIvilVX66vF2uobSumxooYZChiRPCKNqhmg==", "dev": true }, - "node_modules/unstorage/node_modules/listhen": { - "version": "1.0.4", - "resolved": "https://registry.npmjs.org/listhen/-/listhen-1.0.4.tgz", - "integrity": "sha512-r94k7kmXHb8e8wpv7+UP/qqhhD+j/9TgX19QKim2cEJuWCLwlTw+5BkCFmYyjhQ7Bt8KdVun/2DcD7MF2Fe3+g==", - "dev": true, - "dependencies": { - "clipboardy": "^3.0.0", - "colorette": "^2.0.19", - "defu": "^6.1.2", - "get-port-please": "^3.0.1", - "http-shutdown": "^1.2.2", - "ip-regex": "^5.0.0", - "node-forge": "^1.3.1", - "ufo": "^1.1.1" - } - }, "node_modules/unstorage/node_modules/lru-cache": { - "version": "9.1.1", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-9.1.1.tgz", - "integrity": "sha512-65/Jky17UwSb0BuB9V+MyDpsOtXKmYwzhyl+cOa9XUiI4uV2Ouy/2voFP3+al0BjZbJgMBD8FojMpAf+Z+qn4A==", + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.0.2.tgz", + "integrity": "sha512-Yj9mA8fPiVgOUpByoTZO5pNrcl5Yk37FcSHsUINpAsaBIEZIuqcCclDZJCVxqQShDsmYX8QG63svJiTbOATZwg==", "dev": true, + "dependencies": { + "semver": "^7.3.5" + }, "engines": { "node": "14 || >=16.14" } }, - "node_modules/unstorage/node_modules/node-fetch-native": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/node-fetch-native/-/node-fetch-native-1.1.1.tgz", - "integrity": "sha512-9VvspTSUp2Sxbl+9vbZTlFGq9lHwE8GDVVekxx6YsNd1YH59sb3Ba8v3Y3cD8PkLNcileGGcA21PFjVl0jzDaw==", - "dev": true - }, "node_modules/untildify": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/untildify/-/untildify-4.0.0.tgz", @@ -11812,6 +12315,26 @@ "node": ">=8" } }, + "node_modules/untun": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/untun/-/untun-0.1.2.tgz", + "integrity": "sha512-wLAMWvxfqyTiBODA1lg3IXHQtjggYLeTK7RnSfqtOXixWJ3bAa2kK/HHmOOg19upteqO3muLvN6O/icbyQY33Q==", + "dev": true, + "dependencies": { + "citty": "^0.1.3", + "consola": "^3.2.3", + "pathe": "^1.1.1" + }, + "bin": { + "untun": "bin/untun.mjs" + } + }, + "node_modules/untun/node_modules/pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", + "dev": true + }, "node_modules/update-browserslist-db": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.10.tgz", @@ -11837,6 +12360,12 @@ "browserslist": ">= 4.21.0" } }, + "node_modules/uqr": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/uqr/-/uqr-0.1.2.tgz", + "integrity": "sha512-MJu7ypHq6QasgF5YRTjqscSzQp/W11zoUk6kvmlH+fmWEs63Y0Eib13hYFwAzagRJcVY8WVnlV+eBDUGMJ5IbA==", + "dev": true + }, "node_modules/uri-js": { "version": "4.4.1", "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", @@ -11860,6 +12389,12 @@ "resolved": "https://registry.npmjs.org/url-template/-/url-template-2.0.8.tgz", "integrity": "sha1-/FZaPMy/93MMd19WQflVV5FDnyE=" }, + "node_modules/urlpattern-polyfill": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/urlpattern-polyfill/-/urlpattern-polyfill-8.0.2.tgz", + "integrity": "sha512-Qp95D4TPJl1kC9SKigDcqgyM2VDVO4RiJc2d4qe5GrYm+zbIQCWWKAFaJNQ4BhdFeDGwBmAxqJBwWSJDb9T3BQ==", + "dev": true + }, "node_modules/use-isomorphic-layout-effect": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/use-isomorphic-layout-effect/-/use-isomorphic-layout-effect-1.1.2.tgz", @@ -12663,10 +13198,10 @@ "algoliasearch": "^4.0.0" } }, - "@fastify/busboy": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/@fastify/busboy/-/busboy-2.0.0.tgz", - "integrity": "sha512-JUFJad5lv7jxj926GPgymrWQxxjPYuJNiNjNMzqT+HiuP6Vl3dk5xzG+8sTX96np0ZAluvaMzPsjhHZ5rNuNQQ==", + "@fastify/accept-negotiator": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@fastify/accept-negotiator/-/accept-negotiator-1.1.0.tgz", + "integrity": "sha512-OIHZrb2ImZ7XG85HXOONLcJWGosv7sIvM2ifAPQVhg9Lv7qdmMBNVaai4QTdyuaqbKM5eO6sLSQOYI7wEQeCJQ==", "dev": true }, "@fec/remark-a11y-emoji": { @@ -13236,23 +13771,33 @@ } }, "@netlify/ipx": { - "version": "1.4.0", - "resolved": "https://registry.npmjs.org/@netlify/ipx/-/ipx-1.4.0.tgz", - "integrity": "sha512-Ibqg1W41EVMHNT/W6JSDUyxjhcxsbEL9vL9ZaNjn9tVKnDYxJ8JqRTwSbzfns+K+M3FLqoC4PLW32qW+vT1pKQ==", + "version": "1.4.6", + "resolved": "https://registry.npmjs.org/@netlify/ipx/-/ipx-1.4.6.tgz", + "integrity": "sha512-rnKR2LXhtnflitPX9CQIv+XSrNlYIqGsV54xrXifhbtHHjCjCw/lixsi8qwAXqEIgZBC9b4Y7prhHqRtC4oIjw==", "dev": true, "requires": { - "@netlify/functions": "^1.4.0", + "@netlify/functions": "^2.4.0", "etag": "^1.8.1", "fs-extra": "^11.0.0", - "ipx": "^0.9.11", + "ipx": "^1.3.1", "micromatch": "^4.0.5", - "mkdirp": "^1.0.4", + "mkdirp": "^3.0.0", "murmurhash": "^2.0.0", "node-fetch": "^2.0.0", "ufo": "^1.0.0", - "unstorage": "^1.0.0" + "unstorage": "1.9.0" }, "dependencies": { + "@netlify/functions": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/@netlify/functions/-/functions-2.4.0.tgz", + "integrity": "sha512-dIqhdj5u4Lu/8qbYwtYpn8NfvIyPHbSTV2lAP4ocL+iwC9As06AXT0wa/xOpO2vRWJa0IMxdZaqCPnkyHlHiyg==", + "dev": true, + "requires": { + "@netlify/serverless-functions-api": "1.11.0", + "is-promise": "^4.0.0" + } + }, "fs-extra": { "version": "11.1.1", "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.1.1.tgz", @@ -13266,6 +13811,12 @@ } } }, + "@netlify/node-cookies": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/@netlify/node-cookies/-/node-cookies-0.1.0.tgz", + "integrity": "sha512-OAs1xG+FfLX0LoRASpqzVntVV/RpYkgpI0VrUnw2u0Q1qiZUzcPffxRK8HF3gc4GjuhG5ahOEMJ9bswBiZPq0g==", + "dev": true + }, "@netlify/plugin-nextjs": { "version": "4.37.2", "resolved": "https://registry.npmjs.org/@netlify/plugin-nextjs/-/plugin-nextjs-4.37.2.tgz", @@ -13394,6 +13945,16 @@ } } }, + "@netlify/serverless-functions-api": { + "version": "1.11.0", + "resolved": "https://registry.npmjs.org/@netlify/serverless-functions-api/-/serverless-functions-api-1.11.0.tgz", + "integrity": "sha512-3splAsr2CekL7VTwgo6yTvzD2+f269/s+TJafYazonqMNNo31yzvFxD5HpLtni4DNE1ppymVKZ4X/rLN3yl0vQ==", + "dev": true, + "requires": { + "@netlify/node-cookies": "^0.1.0", + "urlpattern-polyfill": "8.0.2" + } + }, "@next/env": { "version": "12.3.1", "resolved": "https://registry.npmjs.org/@next/env/-/env-12.3.1.tgz", @@ -13558,9 +14119,135 @@ "resolved": "https://registry.npmjs.org/@octokit/types/-/types-6.34.0.tgz", "integrity": "sha512-s1zLBjWhdEI2zwaoSgyOFoKSl109CUcVBCc7biPJ3aAf6LGLU6szDvi31JPU7bxfla2lqfhjbbg/5DdFNxOwHw==", "requires": { - "@octokit/openapi-types": "^11.2.0" + "@octokit/openapi-types": "^11.2.0" + } + }, + "@parcel/watcher": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher/-/watcher-2.3.0.tgz", + "integrity": "sha512-pW7QaFiL11O0BphO+bq3MgqeX/INAk9jgBldVDYjlQPO4VddoZnF22TcF9onMhnLVHuNqBJeRf+Fj7eezi/+rQ==", + "dev": true, + "requires": { + "@parcel/watcher-android-arm64": "2.3.0", + "@parcel/watcher-darwin-arm64": "2.3.0", + "@parcel/watcher-darwin-x64": "2.3.0", + "@parcel/watcher-freebsd-x64": "2.3.0", + "@parcel/watcher-linux-arm-glibc": "2.3.0", + "@parcel/watcher-linux-arm64-glibc": "2.3.0", + "@parcel/watcher-linux-arm64-musl": "2.3.0", + "@parcel/watcher-linux-x64-glibc": "2.3.0", + "@parcel/watcher-linux-x64-musl": "2.3.0", + "@parcel/watcher-win32-arm64": "2.3.0", + "@parcel/watcher-win32-ia32": "2.3.0", + "@parcel/watcher-win32-x64": "2.3.0", + "detect-libc": "^1.0.3", + "is-glob": "^4.0.3", + "micromatch": "^4.0.5", + "node-addon-api": "^7.0.0" + } + }, + "@parcel/watcher-android-arm64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-android-arm64/-/watcher-android-arm64-2.3.0.tgz", + "integrity": "sha512-f4o9eA3dgk0XRT3XhB0UWpWpLnKgrh1IwNJKJ7UJek7eTYccQ8LR7XUWFKqw6aEq5KUNlCcGvSzKqSX/vtWVVA==", + "dev": true, + "optional": true + }, + "@parcel/watcher-darwin-arm64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-darwin-arm64/-/watcher-darwin-arm64-2.3.0.tgz", + "integrity": "sha512-mKY+oijI4ahBMc/GygVGvEdOq0L4DxhYgwQqYAz/7yPzuGi79oXrZG52WdpGA1wLBPrYb0T8uBaGFo7I6rvSKw==", + "dev": true, + "optional": true + }, + "@parcel/watcher-darwin-x64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-darwin-x64/-/watcher-darwin-x64-2.3.0.tgz", + "integrity": "sha512-20oBj8LcEOnLE3mgpy6zuOq8AplPu9NcSSSfyVKgfOhNAc4eF4ob3ldj0xWjGGbOF7Dcy1Tvm6ytvgdjlfUeow==", + "dev": true, + "optional": true + }, + "@parcel/watcher-freebsd-x64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-freebsd-x64/-/watcher-freebsd-x64-2.3.0.tgz", + "integrity": "sha512-7LftKlaHunueAEiojhCn+Ef2CTXWsLgTl4hq0pkhkTBFI3ssj2bJXmH2L67mKpiAD5dz66JYk4zS66qzdnIOgw==", + "dev": true, + "optional": true + }, + "@parcel/watcher-linux-arm-glibc": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-arm-glibc/-/watcher-linux-arm-glibc-2.3.0.tgz", + "integrity": "sha512-1apPw5cD2xBv1XIHPUlq0cO6iAaEUQ3BcY0ysSyD9Kuyw4MoWm1DV+W9mneWI+1g6OeP6dhikiFE6BlU+AToTQ==", + "dev": true, + "optional": true + }, + "@parcel/watcher-linux-arm64-glibc": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-arm64-glibc/-/watcher-linux-arm64-glibc-2.3.0.tgz", + "integrity": "sha512-mQ0gBSQEiq1k/MMkgcSB0Ic47UORZBmWoAWlMrTW6nbAGoLZP+h7AtUM7H3oDu34TBFFvjy4JCGP43JlylkTQA==", + "dev": true, + "optional": true + }, + "@parcel/watcher-linux-arm64-musl": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-arm64-musl/-/watcher-linux-arm64-musl-2.3.0.tgz", + "integrity": "sha512-LXZAExpepJew0Gp8ZkJ+xDZaTQjLHv48h0p0Vw2VMFQ8A+RKrAvpFuPVCVwKJCr5SE+zvaG+Etg56qXvTDIedw==", + "dev": true, + "optional": true + }, + "@parcel/watcher-linux-x64-glibc": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-x64-glibc/-/watcher-linux-x64-glibc-2.3.0.tgz", + "integrity": "sha512-P7Wo91lKSeSgMTtG7CnBS6WrA5otr1K7shhSjKHNePVmfBHDoAOHYRXgUmhiNfbcGk0uMCHVcdbfxtuiZCHVow==", + "dev": true, + "optional": true + }, + "@parcel/watcher-linux-x64-musl": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-linux-x64-musl/-/watcher-linux-x64-musl-2.3.0.tgz", + "integrity": "sha512-+kiRE1JIq8QdxzwoYY+wzBs9YbJ34guBweTK8nlzLKimn5EQ2b2FSC+tAOpq302BuIMjyuUGvBiUhEcLIGMQ5g==", + "dev": true, + "optional": true + }, + "@parcel/watcher-wasm": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-wasm/-/watcher-wasm-2.3.0.tgz", + "integrity": "sha512-ejBAX8H0ZGsD8lSICDNyMbSEtPMWgDL0WFCt/0z7hyf5v8Imz4rAM8xY379mBsECkq/Wdqa5WEDLqtjZ+6NxfA==", + "dev": true, + "requires": { + "is-glob": "^4.0.3", + "micromatch": "^4.0.5", + "napi-wasm": "^1.1.0" + }, + "dependencies": { + "napi-wasm": { + "version": "1.1.0", + "bundled": true, + "dev": true + } } }, + "@parcel/watcher-win32-arm64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-win32-arm64/-/watcher-win32-arm64-2.3.0.tgz", + "integrity": "sha512-35gXCnaz1AqIXpG42evcoP2+sNL62gZTMZne3IackM+6QlfMcJLy3DrjuL6Iks7Czpd3j4xRBzez3ADCj1l7Aw==", + "dev": true, + "optional": true + }, + "@parcel/watcher-win32-ia32": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-win32-ia32/-/watcher-win32-ia32-2.3.0.tgz", + "integrity": "sha512-FJS/IBQHhRpZ6PiCjFt1UAcPr0YmCLHRbTc00IBTrelEjlmmgIVLeOx4MSXzx2HFEy5Jo5YdhGpxCuqCyDJ5ow==", + "dev": true, + "optional": true + }, + "@parcel/watcher-win32-x64": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@parcel/watcher-win32-x64/-/watcher-win32-x64-2.3.0.tgz", + "integrity": "sha512-dLx+0XRdMnVI62kU3wbXvbIRhLck4aE28bIGKbRGS7BJNt54IIj9+c/Dkqb+7DJEbHUZAX1bwaoM8PqVlHJmCA==", + "dev": true, + "optional": true + }, "@slack/logger": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/@slack/logger/-/logger-3.0.0.tgz", @@ -13592,6 +14279,27 @@ "p-retry": "^4.0.0" }, "dependencies": { + "axios": { + "version": "0.27.2", + "resolved": "https://registry.npmjs.org/axios/-/axios-0.27.2.tgz", + "integrity": "sha512-t+yRIyySRTp/wua5xEr+z1q60QmLq8ABsS5O9Me1AsE5dfKqgnCFzwiCZZ/cGNd1lq4/7akDWMxdhVlucjmnOQ==", + "requires": { + "follow-redirects": "^1.14.9", + "form-data": "^4.0.0" + }, + "dependencies": { + "form-data": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.0.tgz", + "integrity": "sha512-ETEklSGi5t0QMZuiXoA/Q6vcnxcLQP5vdugSpuAyi6SVGi2clPPp+xgEhuMaHC+zGgn31Kd235W35f7Hykkaww==", + "requires": { + "asynckit": "^0.4.0", + "combined-stream": "^1.0.8", + "mime-types": "^2.1.12" + } + } + } + }, "form-data": { "version": "2.5.1", "resolved": "https://registry.npmjs.org/form-data/-/form-data-2.5.1.tgz", @@ -14077,14 +14785,28 @@ "dev": true }, "axios": { - "version": "0.27.2", - "resolved": "https://registry.npmjs.org/axios/-/axios-0.27.2.tgz", - "integrity": "sha512-t+yRIyySRTp/wua5xEr+z1q60QmLq8ABsS5O9Me1AsE5dfKqgnCFzwiCZZ/cGNd1lq4/7akDWMxdhVlucjmnOQ==", + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/axios/-/axios-1.6.0.tgz", + "integrity": "sha512-EZ1DYihju9pwVB+jg67ogm+Tmqc6JmhamRN6I4Zt8DfZu5lbcQGw3ozH9lFejSJgs/ibaef3A9PMXPLeefFGJg==", "requires": { - "follow-redirects": "^1.14.9", - "form-data": "^4.0.0" + "follow-redirects": "^1.15.0", + "form-data": "^4.0.0", + "proxy-from-env": "^1.1.0" + }, + "dependencies": { + "proxy-from-env": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz", + "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==" + } } }, + "b4a": { + "version": "1.6.4", + "resolved": "https://registry.npmjs.org/b4a/-/b4a-1.6.4.tgz", + "integrity": "sha512-fpWrvyVHEKyeEvbKZTVOeZF3VSKKWtJxFIxX/jaVPf+cLbGUSitjb49pHLqPV2BUNNZ0LcoeEGfE/YCpyDYHIw==", + "dev": true + }, "babel-code-frame": { "version": "6.26.0", "resolved": "https://registry.npmjs.org/babel-code-frame/-/babel-code-frame-6.26.0.tgz", @@ -14494,6 +15216,15 @@ "integrity": "sha512-eXTggHWSooYhq49F2opQhuHWgzucfF2YgODK4e1566GQs5BIfP30B0oenwBJHfWxAs2fyPB1s7Mg949zLf61Yw==", "dev": true }, + "citty": { + "version": "0.1.4", + "resolved": "https://registry.npmjs.org/citty/-/citty-0.1.4.tgz", + "integrity": "sha512-Q3bK1huLxzQrvj7hImJ7Z1vKYJRPQCDnd0EjXfHMidcjecGOMuLrmuQmtWmFkuKLcMThlGh1yCKG8IEc6VeNXQ==", + "dev": true, + "requires": { + "consola": "^3.2.3" + } + }, "classnames": { "version": "2.2.6", "resolved": "https://registry.npmjs.org/classnames/-/classnames-2.2.6.tgz", @@ -14786,9 +15517,9 @@ } }, "consola": { - "version": "2.15.3", - "resolved": "https://registry.npmjs.org/consola/-/consola-2.15.3.tgz", - "integrity": "sha512-9vAdYbHj6x2fLKC4+oPH0kFzY/orMZyG2Aj+kNylHxKGJ/Ed4dpNyAQYwJOdqO4zdM7XpVHmyejQDcQHrnuXbw==", + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/consola/-/consola-3.2.3.tgz", + "integrity": "sha512-I5qxpzLv+sJhTVEoLYNcTW+bThDCPsit0vLNKShZx6rLtpilNpmmeTPaeqJb9ZE9dV3DGaeby6Vuhrw38WjeyQ==", "dev": true }, "convert-source-map": { @@ -15542,9 +16273,9 @@ "integrity": "sha512-Y2caI5+ZwS5c3RiNDJ6u53VhQHv+hHKwhkI1iHvceKUHw9Df6EK2zRLfjejRgMuCuxK7PfSWIMwWecceVvThjQ==" }, "defu": { - "version": "6.1.2", - "resolved": "https://registry.npmjs.org/defu/-/defu-6.1.2.tgz", - "integrity": "sha512-+uO4+qr7msjNNWKYPHqN/3+Dx3NFkmIzayk2L1MyZQlvgZb/J1A0fo410dpKrN2SnqFjt8n4JL8fDJE0wIgjFQ==", + "version": "6.1.3", + "resolved": "https://registry.npmjs.org/defu/-/defu-6.1.3.tgz", + "integrity": "sha512-Vy2wmG3NTkmHNg/kzpuvHhkqeIx3ODWqasgCRbKtbXEN0G+HpEEv9BtJLp7ZG1CZloFaC41Ah3ZFbq7aqCqMeQ==", "dev": true }, "delaunator": { @@ -15597,9 +16328,9 @@ } }, "detect-libc": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.1.tgz", - "integrity": "sha512-463v3ZeIrcWtdgIg6vI6XUncguvr2TnGl4SzDXinkt9mSLpBJKXT3mW6xT3VQdDN11+WVs29pgvivTc4Lp8v+w==", + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-1.0.3.tgz", + "integrity": "sha512-pGjwhsmsp4kL2RTz08wcOlGN83otlqHeD/Z5T8GXZB+/YcpQ/dgo+lbU8ZsGxV0HIvqqxo9l7mqYwyYMD9bKDg==", "dev": true }, "detective": { @@ -15978,6 +16709,12 @@ "integrity": "sha512-NCe8qxnZFARSHGztGMZOO/PC1qa5MIFB5Hp66WdzbCRAz8U8US3bx1UTgLS49efBQPcUtO9gf5oVEY8o7y/7Kg==", "dev": true }, + "fast-fifo": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/fast-fifo/-/fast-fifo-1.3.2.tgz", + "integrity": "sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ==", + "dev": true + }, "fast-glob": { "version": "3.2.12", "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.12.tgz", @@ -16134,12 +16871,6 @@ "universalify": "^2.0.0" } }, - "fs-memo": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/fs-memo/-/fs-memo-1.2.0.tgz", - "integrity": "sha512-YEexkCpL4j03jn5SxaMHqcO6IuWuqm8JFUYhyCep7Ao89JIYmB8xoKhK7zXXJ9cCaNXpyNH5L3QtAmoxjoHW2w==", - "dev": true - }, "fs.realpath": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", @@ -16210,13 +16941,10 @@ } }, "get-port-please": { - "version": "2.6.1", - "resolved": "https://registry.npmjs.org/get-port-please/-/get-port-please-2.6.1.tgz", - "integrity": "sha512-4PDSrL6+cuMM1xs6w36ZIkaKzzE0xzfVBCfebHIJ3FE8iB9oic/ECwPw3iNiD4h1AoJ5XLLBhEviFAVrZsDC5A==", - "dev": true, - "requires": { - "fs-memo": "^1.2.0" - } + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/get-port-please/-/get-port-please-3.1.1.tgz", + "integrity": "sha512-3UBAyM3u4ZBVYDsxOQfJDxEa6XTbpBDrOjp4mf7ExFRt5BKs/QywQQiJsh2B+hxcZLSapWqCRvElUe8DnKcFHA==", + "dev": true }, "get-stream": { "version": "5.2.0", @@ -16418,18 +17146,27 @@ } }, "h3": { - "version": "1.6.6", - "resolved": "https://registry.npmjs.org/h3/-/h3-1.6.6.tgz", - "integrity": "sha512-DWu2s11OuuO9suEkX99dXaJoxd1RgPXiM4iDmLdrhGV63GLoav13f3Kdd5/Rw7xNKzhzn2+F2dleQjG66SnMPQ==", + "version": "1.8.2", + "resolved": "https://registry.npmjs.org/h3/-/h3-1.8.2.tgz", + "integrity": "sha512-1Ca0orJJlCaiFY68BvzQtP2lKLk46kcLAxVM8JgYbtm2cUg6IY7pjpYgWMwUvDO9QI30N5JAukOKoT8KD3Q0PQ==", "dev": true, "requires": { "cookie-es": "^1.0.0", "defu": "^6.1.2", - "destr": "^1.2.2", - "iron-webcrypto": "^0.7.0", - "radix3": "^1.0.1", - "ufo": "^1.1.2", - "uncrypto": "^0.1.2" + "destr": "^2.0.1", + "iron-webcrypto": "^0.10.1", + "radix3": "^1.1.0", + "ufo": "^1.3.0", + "uncrypto": "^0.1.3", + "unenv": "^1.7.4" + }, + "dependencies": { + "destr": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/destr/-/destr-2.0.2.tgz", + "integrity": "sha512-65AlobnZMiCET00KaFFjUefxDX0khFA/E4myqZ7a6Sq1yZtR8+FVIvilVX66vF2uobSumxooYZChiRPCKNqhmg==", + "dev": true + } } }, "has": { @@ -16944,49 +17681,44 @@ "standard-as-callback": "^2.1.0" } }, - "ip-regex": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/ip-regex/-/ip-regex-5.0.0.tgz", - "integrity": "sha512-fOCG6lhoKKakwv+C6KdsOnGvgXnmgfmp0myi3bcNwj3qfwPAxRKWEuFhvEFF7ceYIz6+1jRZ+yguLFAmUNPEfw==", - "dev": true - }, "ipx": { - "version": "0.9.11", - "resolved": "https://registry.npmjs.org/ipx/-/ipx-0.9.11.tgz", - "integrity": "sha512-/wsBt7hV8rvNR6O4kwgOUAhtm0F/M/mXaolXot/Bz7fdOD+W7i9OtWuoASWv1PFwwtOunhZGaoCx8BOpSdG2VQ==", + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/ipx/-/ipx-1.3.1.tgz", + "integrity": "sha512-hWRLXdMDOz2q81T2x9lowFtAGO3E5b2HtC8xOOBTrlnxygHNaVrZqJ5c1P3T7tDkC3oCocYRRz0VBffvJKeQlw==", "dev": true, "requires": { - "consola": "^2.15.3", - "defu": "^6.1.0", - "destr": "^1.1.1", + "@fastify/accept-negotiator": "^1.1.0", + "consola": "^3.2.3", + "defu": "^6.1.2", + "destr": "^2.0.1", "etag": "^1.8.1", "image-meta": "^0.1.1", - "listhen": "^0.2.15", - "ohmyfetch": "^0.4.18", - "pathe": "^0.3.5", - "sharp": "^0.30.7", - "ufo": "^0.8.5", + "listhen": "^1.5.5", + "node-fetch-native": "^1.4.0", + "pathe": "^1.1.1", + "sharp": "^0.32.6", + "ufo": "^1.3.1", "xss": "^1.0.14" }, "dependencies": { - "pathe": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/pathe/-/pathe-0.3.9.tgz", - "integrity": "sha512-6Y6s0vT112P3jD8dGfuS6r+lpa0qqNrLyHPOwvXMnyNTQaYiwgau2DP3aNDsR13xqtGj7rrPo+jFUATpU6/s+g==", + "destr": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/destr/-/destr-2.0.2.tgz", + "integrity": "sha512-65AlobnZMiCET00KaFFjUefxDX0khFA/E4myqZ7a6Sq1yZtR8+FVIvilVX66vF2uobSumxooYZChiRPCKNqhmg==", "dev": true }, - "ufo": { - "version": "0.8.6", - "resolved": "https://registry.npmjs.org/ufo/-/ufo-0.8.6.tgz", - "integrity": "sha512-fk6CmUgwKCfX79EzcDQQpSCMxrHstvbLswFChHS0Vump+kFkw7nJBfTZoC1j0bOGoY9I7R3n2DGek5ajbcYnOw==", + "pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", "dev": true } } }, "iron-webcrypto": { - "version": "0.7.0", - "resolved": "https://registry.npmjs.org/iron-webcrypto/-/iron-webcrypto-0.7.0.tgz", - "integrity": "sha512-WkX32iTcwd79ZsWRPP5wq1Jq6XXfPwO783ZiUBY8uMw4/AByx5WvBmxvYGnpVt6AOVJ0F41Qo420r8lIneT9Wg==", + "version": "0.10.1", + "resolved": "https://registry.npmjs.org/iron-webcrypto/-/iron-webcrypto-0.10.1.tgz", + "integrity": "sha512-QGOS8MRMnj/UiOa+aMIgfyHcvkhqNUsUxb1XzskENvbo+rEfp6TOwqd1KPuDzXC4OnGHcMSVxDGRoilqB8ViqA==", "dev": true }, "is-alphabetical": { @@ -17253,6 +17985,12 @@ "resolved": "https://registry.npmjs.org/jgexml/-/jgexml-0.4.4.tgz", "integrity": "sha512-j0AzSWT7LXy3s3i1cdv5NZxUtscocwiBxgOLiEBfitCehm8STdXVrcOlbAWsJFLCq1elZYpQlGqA9k8Z+n9iJA==" }, + "jiti": { + "version": "1.21.0", + "resolved": "https://registry.npmjs.org/jiti/-/jiti-1.21.0.tgz", + "integrity": "sha512-gFqAIbuKyyso/3G2qhiO2OM6shY6EPP/R0+mkDbyspxKazh8BXDC5FiFsUjlczgdNz/vfra0da2y+aHrusLG/Q==", + "dev": true + }, "js-cookie": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/js-cookie/-/js-cookie-3.0.1.tgz", @@ -17318,6 +18056,12 @@ "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz", "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==" }, + "jsonc-parser": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz", + "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==", + "dev": true + }, "jsonfile": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", @@ -17405,24 +18149,34 @@ } }, "listhen": { - "version": "0.2.15", - "resolved": "https://registry.npmjs.org/listhen/-/listhen-0.2.15.tgz", - "integrity": "sha512-F/IWj/aJLeokHAIVY+l3JoWRUnbRaf2F0cr+Ybc1YyozMA/yP0C2nf3c0Oi7vAbFvtfiwfWWfP7bIrQc/u5L1A==", + "version": "1.5.5", + "resolved": "https://registry.npmjs.org/listhen/-/listhen-1.5.5.tgz", + "integrity": "sha512-LXe8Xlyh3gnxdv4tSjTjscD1vpr/2PRpzq8YIaMJgyKzRG8wdISlWVWnGThJfHnlJ6hmLt2wq1yeeix0TEbuoA==", "dev": true, "requires": { + "@parcel/watcher": "^2.3.0", + "@parcel/watcher-wasm": "2.3.0", + "citty": "^0.1.4", "clipboardy": "^3.0.0", - "colorette": "^2.0.19", - "defu": "^6.0.0", - "get-port-please": "^2.6.1", + "consola": "^3.2.3", + "defu": "^6.1.2", + "get-port-please": "^3.1.1", + "h3": "^1.8.1", "http-shutdown": "^1.2.2", - "selfsigned": "^2.0.1", - "ufo": "^0.8.5" + "jiti": "^1.20.0", + "mlly": "^1.4.2", + "node-forge": "^1.3.1", + "pathe": "^1.1.1", + "std-env": "^3.4.3", + "ufo": "^1.3.0", + "untun": "^0.1.2", + "uqr": "^0.1.2" }, "dependencies": { - "ufo": { - "version": "0.8.6", - "resolved": "https://registry.npmjs.org/ufo/-/ufo-0.8.6.tgz", - "integrity": "sha512-fk6CmUgwKCfX79EzcDQQpSCMxrHstvbLswFChHS0Vump+kFkw7nJBfTZoC1j0bOGoY9I7R3n2DGek5ajbcYnOw==", + "pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", "dev": true } } @@ -18390,6 +19144,12 @@ "picomatch": "^2.3.1" } }, + "mime": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/mime/-/mime-3.0.0.tgz", + "integrity": "sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A==", + "dev": true + }, "mime-db": { "version": "1.52.0", "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz", @@ -18496,9 +19256,9 @@ } }, "mkdirp": { - "version": "1.0.4", - "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz", - "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==", + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-3.0.1.tgz", + "integrity": "sha512-+NsyUUAZDmo6YVHzL/stxSu3t9YS1iljliy3BSDrXJ/dkn1KYdmtZODGGjLcc9XLgVVpH4KshHB8XmZgMhaBXg==", "dev": true }, "mkdirp-classic": { @@ -18507,6 +19267,32 @@ "integrity": "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==", "dev": true }, + "mlly": { + "version": "1.4.2", + "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.4.2.tgz", + "integrity": "sha512-i/Ykufi2t1EZ6NaPLdfnZk2AX8cs0d+mTzVKuPfqPKPatxLApaBoxJQ9x1/uckXtrS/U5oisPMDkNs0yQTaBRg==", + "dev": true, + "requires": { + "acorn": "^8.10.0", + "pathe": "^1.1.1", + "pkg-types": "^1.0.3", + "ufo": "^1.3.0" + }, + "dependencies": { + "acorn": { + "version": "8.11.2", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.11.2.tgz", + "integrity": "sha512-nc0Axzp/0FILLEVsm4fNwLCwMttvhEI263QtVPQcbpfZZ3ts0hLsZGOpE6czNlid7CJ9MlyH8reXkpsf3YUY4w==", + "dev": true + }, + "pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", + "dev": true + } + } + }, "moize": { "version": "6.1.6", "resolved": "https://registry.npmjs.org/moize/-/moize-6.1.6.tgz", @@ -18649,18 +19435,18 @@ } }, "node-abi": { - "version": "3.40.0", - "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.40.0.tgz", - "integrity": "sha512-zNy02qivjjRosswoYmPi8hIKJRr8MpQyeKT6qlcq/OnOgA3Rhoae+IYOqsM9V5+JnHWmxKnWOT2GxvtqdtOCXA==", + "version": "3.51.0", + "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.51.0.tgz", + "integrity": "sha512-SQkEP4hmNWjlniS5zdnfIXTk1x7Ome85RDzHlTbBtzE97Gfwz/Ipw4v/Ryk20DWIy3yCNVLVlGKApCnmvYoJbA==", "dev": true, "requires": { "semver": "^7.3.5" } }, "node-addon-api": { - "version": "5.1.0", - "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-5.1.0.tgz", - "integrity": "sha512-eh0GgfEkpnoWDq+VY8OyvYhFEzBk6jIYbRKdIlyTiAXIVJ8PyBaKb0rp7oDtoddbdoHWhq8wwr+XZ81F1rpNdA==", + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.0.0.tgz", + "integrity": "sha512-vgbBJTS4m5/KkE16t5Ly0WW9hz46swAstv0hYYwMtbG7AznRhNyfLRe8HZAiWIpcHzoO7HxhLuBQj9rJ/Ho0ZA==", "dev": true }, "node-fetch": { @@ -18672,9 +19458,9 @@ } }, "node-fetch-native": { - "version": "0.1.8", - "resolved": "https://registry.npmjs.org/node-fetch-native/-/node-fetch-native-0.1.8.tgz", - "integrity": "sha512-ZNaury9r0NxaT2oL65GvdGDy+5PlSaHTovT6JV5tOW07k1TQmgC0olZETa4C9KZg0+6zBr99ctTYa3Utqj9P/Q==", + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/node-fetch-native/-/node-fetch-native-1.4.1.tgz", + "integrity": "sha512-NsXBU0UgBxo2rQLOeWNZqS3fvflWePMECr8CoSWoSTqCqGbVVsvl9vZu1HfQicYN0g5piV9Gh8RTEvo/uP752w==", "dev": true }, "node-forge": { @@ -18761,40 +19547,20 @@ } }, "ofetch": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/ofetch/-/ofetch-1.0.1.tgz", - "integrity": "sha512-icBz2JYfEpt+wZz1FRoGcrMigjNKjzvufE26m9+yUiacRQRHwnNlGRPiDnW4op7WX/MR6aniwS8xw8jyVelF2g==", - "dev": true, - "requires": { - "destr": "^1.2.2", - "node-fetch-native": "^1.0.2", - "ufo": "^1.1.0" - }, - "dependencies": { - "node-fetch-native": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/node-fetch-native/-/node-fetch-native-1.1.1.tgz", - "integrity": "sha512-9VvspTSUp2Sxbl+9vbZTlFGq9lHwE8GDVVekxx6YsNd1YH59sb3Ba8v3Y3cD8PkLNcileGGcA21PFjVl0jzDaw==", - "dev": true - } - } - }, - "ohmyfetch": { - "version": "0.4.21", - "resolved": "https://registry.npmjs.org/ohmyfetch/-/ohmyfetch-0.4.21.tgz", - "integrity": "sha512-VG7f/JRvqvBOYvL0tHyEIEG7XHWm7OqIfAs6/HqwWwDfjiJ1g0huIpe5sFEmyb+7hpFa1EGNH2aERWR72tlClw==", + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/ofetch/-/ofetch-1.3.3.tgz", + "integrity": "sha512-s1ZCMmQWXy4b5K/TW9i/DtiN8Ku+xCiHcjQ6/J/nDdssirrQNOoB165Zu8EqLMA2lln1JUth9a0aW9Ap2ctrUg==", "dev": true, "requires": { - "destr": "^1.2.0", - "node-fetch-native": "^0.1.8", - "ufo": "^0.8.6", - "undici": "^5.12.0" + "destr": "^2.0.1", + "node-fetch-native": "^1.4.0", + "ufo": "^1.3.0" }, "dependencies": { - "ufo": { - "version": "0.8.6", - "resolved": "https://registry.npmjs.org/ufo/-/ufo-0.8.6.tgz", - "integrity": "sha512-fk6CmUgwKCfX79EzcDQQpSCMxrHstvbLswFChHS0Vump+kFkw7nJBfTZoC1j0bOGoY9I7R3n2DGek5ajbcYnOw==", + "destr": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/destr/-/destr-2.0.2.tgz", + "integrity": "sha512-65AlobnZMiCET00KaFFjUefxDX0khFA/E4myqZ7a6Sq1yZtR8+FVIvilVX66vF2uobSumxooYZChiRPCKNqhmg==", "dev": true } } @@ -19120,6 +19886,25 @@ "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==" }, + "pkg-types": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/pkg-types/-/pkg-types-1.0.3.tgz", + "integrity": "sha512-nN7pYi0AQqJnoLPC9eHFQ8AcyaixBUOwvqc5TDnIKCMEE6I0y8P7OKA7fPexsXGCGxQDl/cmrLAp26LhcwxZ4A==", + "dev": true, + "requires": { + "jsonc-parser": "^3.2.0", + "mlly": "^1.2.0", + "pathe": "^1.1.0" + }, + "dependencies": { + "pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", + "dev": true + } + } + }, "point-in-polygon": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/point-in-polygon/-/point-in-polygon-1.1.0.tgz", @@ -19586,6 +20371,50 @@ "simple-get": "^4.0.0", "tar-fs": "^2.0.0", "tunnel-agent": "^0.6.0" + }, + "dependencies": { + "detect-libc": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.2.tgz", + "integrity": "sha512-UX6sGumvvqSaXgdKGUsgZWqcUyIXZ/vZTrlRT/iobiKhGL0zL4d3osHj3uqllWJK+i+sixDS/3COVEOFbupFyw==", + "dev": true + }, + "readable-stream": { + "version": "3.6.2", + "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz", + "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==", + "dev": true, + "requires": { + "inherits": "^2.0.3", + "string_decoder": "^1.1.1", + "util-deprecate": "^1.0.1" + } + }, + "tar-fs": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.1.tgz", + "integrity": "sha512-V0r2Y9scmbDRLCNex/+hYzvp/zyYjvFbHPNgVTKfQvVrb6guiE/fxP+XblDNR011utopbkex2nM4dHNV6GDsng==", + "dev": true, + "requires": { + "chownr": "^1.1.1", + "mkdirp-classic": "^0.5.2", + "pump": "^3.0.0", + "tar-stream": "^2.1.4" + } + }, + "tar-stream": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz", + "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==", + "dev": true, + "requires": { + "bl": "^4.0.3", + "end-of-stream": "^1.4.1", + "fs-constants": "^1.0.0", + "inherits": "^2.0.3", + "readable-stream": "^3.1.1" + } + } } }, "pretty-bytes": { @@ -19717,15 +20546,21 @@ "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==" }, + "queue-tick": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/queue-tick/-/queue-tick-1.0.1.tgz", + "integrity": "sha512-kJt5qhMxoszgU/62PLP1CJytzd2NKetjSRnyuj31fDd3Rlcz3fzlFdFLD1SItunPwyqEOkca6GbV612BWfaBag==", + "dev": true + }, "quick-lru": { "version": "5.1.1", "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-5.1.1.tgz", "integrity": "sha512-WuyALRjWPDGtt/wzJiadO5AXY+8hZ80hVpe6MyivgraREW751X3SbhRvG3eLKOYN+8VEvqLcf3wdnt44Z4S4SA==" }, "radix3": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/radix3/-/radix3-1.0.1.tgz", - "integrity": "sha512-y+AcwZ3HcUIGc9zGsNVf5+BY/LxL+z+4h4J3/pp8jxSmy1STaCocPS3qrj4tA5ehUSzqtqK+0Aygvz/r/8vy4g==", + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/radix3/-/radix3-1.1.0.tgz", + "integrity": "sha512-pNsHDxbGORSvuSScqNJ+3Km6QAVqk8CfsCBIEoDgpqLrkD2f3QM4I7d1ozJJ172OmIcoUcerZaNWqtLkRXTV3A==", "dev": true }, "raf": { @@ -19784,12 +20619,6 @@ "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz", "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==", "dev": true - }, - "strip-json-comments": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz", - "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==", - "dev": true } } }, @@ -20370,15 +21199,6 @@ "integrity": "sha512-OwpTSOfy6xSs1+pwcNrv0RBMOzI39Lp3qQKUTPVVPRjCdNa5JH/oPRiqsesIskK8TVgmRiHwO4KXlV2Li9dANA==", "optional": true }, - "selfsigned": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/selfsigned/-/selfsigned-2.1.1.tgz", - "integrity": "sha512-GSL3aowiF7wa/WtSFwnUrludWFoNhftq8bUkH9pkzjpN2XSPOAYEgg6e0sS9s0rZwgJzJiQRPU18A6clnoW5wQ==", - "dev": true, - "requires": { - "node-forge": "^1" - } - }, "semver": { "version": "7.5.4", "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.4.tgz", @@ -20402,19 +21222,33 @@ "integrity": "sha1-KQy7Iy4waULX1+qbg3Mqt4VvgoU=" }, "sharp": { - "version": "0.30.7", - "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.30.7.tgz", - "integrity": "sha512-G+MY2YW33jgflKPTXXptVO28HvNOo9G3j0MybYAHeEmby+QuD2U98dT6ueht9cv/XDqZspSpIhoSW+BAKJ7Hig==", + "version": "0.32.6", + "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.32.6.tgz", + "integrity": "sha512-KyLTWwgcR9Oe4d9HwCwNM2l7+J0dUQwn/yf7S0EnTtb0eVS4RxO0eUSvxPtzT4F3SY+C4K6fqdv/DO27sJ/v/w==", "dev": true, "requires": { "color": "^4.2.3", - "detect-libc": "^2.0.1", - "node-addon-api": "^5.0.0", + "detect-libc": "^2.0.2", + "node-addon-api": "^6.1.0", "prebuild-install": "^7.1.1", - "semver": "^7.3.7", + "semver": "^7.5.4", "simple-get": "^4.0.1", - "tar-fs": "^2.1.1", + "tar-fs": "^3.0.4", "tunnel-agent": "^0.6.0" + }, + "dependencies": { + "detect-libc": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.2.tgz", + "integrity": "sha512-UX6sGumvvqSaXgdKGUsgZWqcUyIXZ/vZTrlRT/iobiKhGL0zL4d3osHj3uqllWJK+i+sixDS/3COVEOFbupFyw==", + "dev": true + }, + "node-addon-api": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-6.1.0.tgz", + "integrity": "sha512-+eawOlIgy680F0kBzPUNFhMZGtJ1YmqM6l4+Crf4IkImjYrO/mqPwRMh352g23uIaQKFItcQ64I7KMaJxHgAVA==", + "dev": true + } } }, "shebang-command": { @@ -20596,6 +21430,22 @@ "resolved": "https://registry.npmjs.org/state-toggle/-/state-toggle-1.0.3.tgz", "integrity": "sha512-d/5Z4/2iiCnHw6Xzghyhb+GcmF89bxwgXG60wjIiZaxnymbyOmI8Hk4VqHXiVVp6u2ysaskFfXg3ekCj4WNftQ==" }, + "std-env": { + "version": "3.5.0", + "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.5.0.tgz", + "integrity": "sha512-JGUEaALvL0Mf6JCfYnJOTcobY+Nc7sG/TemDRBqCA0wEr4DER7zDchaaixTlmOxAjG1uRJmX82EQcxwTQTkqVA==", + "dev": true + }, + "streamx": { + "version": "2.15.5", + "resolved": "https://registry.npmjs.org/streamx/-/streamx-2.15.5.tgz", + "integrity": "sha512-9thPGMkKC2GctCzyCUjME3yR03x2xNo0GPKGkRw2UMYN+gqWa9uqpyNWhmsNCutU5zHmkUum0LsCRQTXUgUCAg==", + "dev": true, + "requires": { + "fast-fifo": "^1.1.0", + "queue-tick": "^1.0.1" + } + }, "string_decoder": { "version": "1.3.0", "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz", @@ -20670,6 +21520,12 @@ "integrity": "sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==", "dev": true }, + "strip-json-comments": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz", + "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==", + "dev": true + }, "style-to-object": { "version": "0.4.1", "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-0.4.1.tgz", @@ -20846,41 +21702,25 @@ } }, "tar-fs": { - "version": "2.1.1", - "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.1.tgz", - "integrity": "sha512-V0r2Y9scmbDRLCNex/+hYzvp/zyYjvFbHPNgVTKfQvVrb6guiE/fxP+XblDNR011utopbkex2nM4dHNV6GDsng==", + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-3.0.4.tgz", + "integrity": "sha512-5AFQU8b9qLfZCX9zp2duONhPmZv0hGYiBPJsyUdqMjzq/mqVpy/rEUSeHk1+YitmxugaptgBh5oDGU3VsAJq4w==", "dev": true, "requires": { - "chownr": "^1.1.1", "mkdirp-classic": "^0.5.2", "pump": "^3.0.0", - "tar-stream": "^2.1.4" + "tar-stream": "^3.1.5" } }, "tar-stream": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz", - "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==", + "version": "3.1.6", + "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-3.1.6.tgz", + "integrity": "sha512-B/UyjYwPpMBv+PaFSWAmtYjwdrlEaZQEhMIBFNC5oEG8lpiW8XjcSdmEaClj28ArfKScKHs2nshz3k2le6crsg==", "dev": true, "requires": { - "bl": "^4.0.3", - "end-of-stream": "^1.4.1", - "fs-constants": "^1.0.0", - "inherits": "^2.0.3", - "readable-stream": "^3.1.1" - }, - "dependencies": { - "readable-stream": { - "version": "3.6.2", - "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz", - "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==", - "dev": true, - "requires": { - "inherits": "^2.0.3", - "string_decoder": "^1.1.1", - "util-deprecate": "^1.0.1" - } - } + "b4a": "^1.6.4", + "fast-fifo": "^1.2.0", + "streamx": "^2.15.0" } }, "throttleit": { @@ -21053,24 +21893,36 @@ "integrity": "sha512-qLK/Xe9E2uzmYI3qLeOmI0tEOt+TBBQyUIAh4aAgU05FVYzeZrKUdkAZfBNVGRaHVgV0TDkdEngJSw/SyQchkQ==" }, "ufo": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.1.2.tgz", - "integrity": "sha512-TrY6DsjTQQgyS3E3dBaOXf0TpPD8u9FVrVYmKVegJuFw51n/YB9XPt+U6ydzFG5ZIN7+DIjPbNmXoBj9esYhgQ==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.3.2.tgz", + "integrity": "sha512-o+ORpgGwaYQXgqGDwd+hkS4PuZ3QnmqMMxRuajK/a38L6fTpcE5GPIfrf+L/KemFzfUpeUQc1rRS1iDBozvnFA==", "dev": true }, "uncrypto": { - "version": "0.1.2", - "resolved": "https://registry.npmjs.org/uncrypto/-/uncrypto-0.1.2.tgz", - "integrity": "sha512-kuZwRKV615lEw/Xx3Iz56FKk3nOeOVGaVmw0eg+x4Mne28lCotNFbBhDW7dEBCBKyKbRQiCadEZeNAFPVC5cgw==", + "version": "0.1.3", + "resolved": "https://registry.npmjs.org/uncrypto/-/uncrypto-0.1.3.tgz", + "integrity": "sha512-Ql87qFHB3s/De2ClA9e0gsnS6zXG27SkTiSJwjCc9MebbfapQfuPzumMIUMi38ezPZVNFcHI9sUIepeQfw8J8Q==", "dev": true }, - "undici": { - "version": "5.26.3", - "resolved": "https://registry.npmjs.org/undici/-/undici-5.26.3.tgz", - "integrity": "sha512-H7n2zmKEWgOllKkIUkLvFmsJQj062lSm3uA4EYApG8gLuiOM0/go9bIoC3HVaSnfg4xunowDE2i9p8drkXuvDw==", + "unenv": { + "version": "1.7.4", + "resolved": "https://registry.npmjs.org/unenv/-/unenv-1.7.4.tgz", + "integrity": "sha512-fjYsXYi30It0YCQYqLOcT6fHfMXsBr2hw9XC7ycf8rTG7Xxpe3ZssiqUnD0khrjiZEmkBXWLwm42yCSCH46fMw==", "dev": true, "requires": { - "@fastify/busboy": "^2.0.0" + "consola": "^3.2.3", + "defu": "^6.1.2", + "mime": "^3.0.0", + "node-fetch-native": "^1.4.0", + "pathe": "^1.1.1" + }, + "dependencies": { + "pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", + "dev": true + } } }, "unherit": { @@ -21212,57 +22064,38 @@ "dev": true }, "unstorage": { - "version": "1.6.1", - "resolved": "https://registry.npmjs.org/unstorage/-/unstorage-1.6.1.tgz", - "integrity": "sha512-GUJzwbP5IStEGZy9/0peRqef5CY9icqApsSu8vxj13admjISyz1g5eYk2wPRBjmZhQ3DUMQ36q+zwTbe68khew==", + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/unstorage/-/unstorage-1.9.0.tgz", + "integrity": "sha512-VpD8ZEYc/le8DZCrny3bnqKE4ZjioQxBRnWE+j5sGNvziPjeDlaS1NaFFHzl/kkXaO3r7UaF8MGQrs14+1B4pQ==", "dev": true, "requires": { "anymatch": "^3.1.3", "chokidar": "^3.5.3", - "destr": "^1.2.2", - "h3": "^1.6.6", + "destr": "^2.0.1", + "h3": "^1.7.1", "ioredis": "^5.3.2", - "listhen": "^1.0.4", - "lru-cache": "^9.1.1", + "listhen": "^1.2.2", + "lru-cache": "^10.0.0", "mri": "^1.2.0", - "node-fetch-native": "^1.1.1", - "ofetch": "^1.0.1", - "ufo": "^1.1.2" + "node-fetch-native": "^1.2.0", + "ofetch": "^1.1.1", + "ufo": "^1.2.0" }, "dependencies": { - "get-port-please": { - "version": "3.0.1", - "resolved": "https://registry.npmjs.org/get-port-please/-/get-port-please-3.0.1.tgz", - "integrity": "sha512-R5pcVO8Z1+pVDu8Ml3xaJCEkBiiy1VQN9za0YqH8GIi1nIqD4IzQhzY6dDzMRtdS1lyiGlucRzm8IN8wtLIXng==", + "destr": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/destr/-/destr-2.0.2.tgz", + "integrity": "sha512-65AlobnZMiCET00KaFFjUefxDX0khFA/E4myqZ7a6Sq1yZtR8+FVIvilVX66vF2uobSumxooYZChiRPCKNqhmg==", "dev": true }, - "listhen": { - "version": "1.0.4", - "resolved": "https://registry.npmjs.org/listhen/-/listhen-1.0.4.tgz", - "integrity": "sha512-r94k7kmXHb8e8wpv7+UP/qqhhD+j/9TgX19QKim2cEJuWCLwlTw+5BkCFmYyjhQ7Bt8KdVun/2DcD7MF2Fe3+g==", + "lru-cache": { + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.0.2.tgz", + "integrity": "sha512-Yj9mA8fPiVgOUpByoTZO5pNrcl5Yk37FcSHsUINpAsaBIEZIuqcCclDZJCVxqQShDsmYX8QG63svJiTbOATZwg==", "dev": true, "requires": { - "clipboardy": "^3.0.0", - "colorette": "^2.0.19", - "defu": "^6.1.2", - "get-port-please": "^3.0.1", - "http-shutdown": "^1.2.2", - "ip-regex": "^5.0.0", - "node-forge": "^1.3.1", - "ufo": "^1.1.1" + "semver": "^7.3.5" } - }, - "lru-cache": { - "version": "9.1.1", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-9.1.1.tgz", - "integrity": "sha512-65/Jky17UwSb0BuB9V+MyDpsOtXKmYwzhyl+cOa9XUiI4uV2Ouy/2voFP3+al0BjZbJgMBD8FojMpAf+Z+qn4A==", - "dev": true - }, - "node-fetch-native": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/node-fetch-native/-/node-fetch-native-1.1.1.tgz", - "integrity": "sha512-9VvspTSUp2Sxbl+9vbZTlFGq9lHwE8GDVVekxx6YsNd1YH59sb3Ba8v3Y3cD8PkLNcileGGcA21PFjVl0jzDaw==", - "dev": true } } }, @@ -21272,6 +22105,25 @@ "integrity": "sha512-KK8xQ1mkzZeg9inewmFVDNkg3l5LUhoq9kN6iWYB/CC9YMG8HA+c1Q8HwDe6dEX7kErrEVNVBO3fWsVq5iDgtw==", "dev": true }, + "untun": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/untun/-/untun-0.1.2.tgz", + "integrity": "sha512-wLAMWvxfqyTiBODA1lg3IXHQtjggYLeTK7RnSfqtOXixWJ3bAa2kK/HHmOOg19upteqO3muLvN6O/icbyQY33Q==", + "dev": true, + "requires": { + "citty": "^0.1.3", + "consola": "^3.2.3", + "pathe": "^1.1.1" + }, + "dependencies": { + "pathe": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.1.tgz", + "integrity": "sha512-d+RQGp0MAYTIaDBIMmOfMwz3E+LOZnxx1HZd5R18mmCZY0QBlK0LDZfPc8FW8Ed2DlvsuE6PRjroDY+wg4+j/Q==", + "dev": true + } + } + }, "update-browserslist-db": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.10.tgz", @@ -21281,6 +22133,12 @@ "picocolors": "^1.0.0" } }, + "uqr": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/uqr/-/uqr-0.1.2.tgz", + "integrity": "sha512-MJu7ypHq6QasgF5YRTjqscSzQp/W11zoUk6kvmlH+fmWEs63Y0Eib13hYFwAzagRJcVY8WVnlV+eBDUGMJ5IbA==", + "dev": true + }, "uri-js": { "version": "4.4.1", "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", @@ -21304,6 +22162,12 @@ "resolved": "https://registry.npmjs.org/url-template/-/url-template-2.0.8.tgz", "integrity": "sha1-/FZaPMy/93MMd19WQflVV5FDnyE=" }, + "urlpattern-polyfill": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/urlpattern-polyfill/-/urlpattern-polyfill-8.0.2.tgz", + "integrity": "sha512-Qp95D4TPJl1kC9SKigDcqgyM2VDVO4RiJc2d4qe5GrYm+zbIQCWWKAFaJNQ4BhdFeDGwBmAxqJBwWSJDb9T3BQ==", + "dev": true + }, "use-isomorphic-layout-effect": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/use-isomorphic-layout-effect/-/use-isomorphic-layout-effect-1.1.2.tgz", diff --git a/package.json b/package.json index 0ec8b5d2d7c..4143d2049dc 100644 --- a/package.json +++ b/package.json @@ -54,7 +54,7 @@ "ajv": "^8.11.0", "ajv-formats": "^2.1.1", "autoprefixer": "^10.4.7", - "axios": "^0.27.2", + "axios": "^1.6.0", "clsx": "^1.1.1", "cssnano": "^5.1.12", "dotenv": "^8.2.0", diff --git a/pages/blog/release-notes-3.0.0.md b/pages/blog/release-notes-3.0.0.md new file mode 100644 index 00000000000..75447e63540 --- /dev/null +++ b/pages/blog/release-notes-3.0.0.md @@ -0,0 +1,362 @@ +--- +title: AsyncAPI 3.0.0 Release Notes +date: 2023-12-05T17:00:00+01:00 +type: Communication +tags: + - Specification + - Release Notes +cover: /img/posts/release-notes-3.0.0/cover.webp +authors: + - name: Jonas Lagoni + photo: /img/avatars/jonaslagoni.webp + link: https://github.com/jonaslagoni +excerpt: 'The release of AsyncAPI v3 is packed with changes such as request/reply, reusable channels, and more!' +featured: true +--- + +The new version of the AsyncAPI specification - 3.0.0 - is now available and is packed with goodies! Some clear up confusion, some add features, and others improve maintainability. + +To make the information as clear as possible, we have split up the information into digestible chunks. + +If you want to get an overview of: +- All the changes done in v3, you are in the right place! +- [Migration guide for all the breaking changes between v2 and v3](/docs/migration/migrating-to-v3) + +## Overview +This post will give you an overview of all the changes done in v3. + +### Operation, channel, and message decoupling + +In v2, it has never been possible to re-use channels, because it was directly coupled with operations of an application. + +In v3, this is now possible, with the mindset that a channel and message should be detached from the operations performed. This means for any message broker, for example, for Kafka, channels now ONLY define topics and the messages it contains. For REST interfaces, it's all the paths and corresponding messages across all request types. For WebSocket, it's all the messages flowing through the WebSocket server. For Socket.Io, it defines all the rooms and messages therein. + +This change makes the channels reusable across multiple AsyncAPI documents. + +``` +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" +``` + +| Issue(s) | PR(s) | Migration Guide | +| ----------- | ----------- | ----------- | +| [#618](https://github.com/asyncapi/spec/issues/618), [#663](https://github.com/asyncapi/spec/issues/663) | [#806](https://github.com/asyncapi/spec/pull/806), [#827](https://github.com/asyncapi/spec/pull/827) | [Operation, channel, and message decoupling](/docs/migration/migrating-to-v3#operation-channel-and-message-decoupling) | + +### Messages instead of message +As you probably noticed above, messages in channels are no longer singular, and with `oneOf`, instead, messages are defined as key/value pairs in the [Messages Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#messagesObject). This was part of the request-reply feature to enable easier referencing of messages. + +``` +asyncapi: 3.0.0 +... +channels: + UserSignup: + address: user/signedup + messages: + UserMessage: + ... +``` + +| Issue(s) | PR(s) | Migration Guide | +| ----------- | ----------- | ----------- | +| [#94](https://github.com/asyncapi/spec/issues/94) | [#827](https://github.com/asyncapi/spec/pull/827) | [Messages instead of message](/docs/migration/migrating-to-v3#messages-instead-of-message) | + +### Publish and subscribe confusion +In v2, the `publish` and `subscribe` operation keywords have always been confusing. Does it mean my application is published to the channel? Does it mean you publish for me? Who are you in this context? + +In v3, we try to clear this up. You only need to worry about your application's behavior. No more confusion about what and who does what. We achieve this through two new [Operation Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject) keywords, `send` and `receive`, i.e. your application either sends or receives something. + +This description, of course, alters slightly based on protocol; for the generic message brokers, you produce or consume messages, but in the abstract AsyncAPI perspective, you still send or receive messages. + +``` +asyncapi: 3.0.0 +... +operations: + SendUserSignedUp: + action: send + ReceiveUserSignedUp: + action: receive +``` + +| Issue(s) | PR(s) | Migration Guide | +| ----------- | ----------- | ----------- | +| [#829](https://github.com/asyncapi/spec/issues/829) | [#847](https://github.com/asyncapi/spec/pull/847) | [Operation keywords](/docs/migration/migrating-to-v3#operation-keywords) | + +### Request/Reply +One of the longest requested features is request and reply... and it's finally here! + +One thorn in the eye of this feature has always been the publish and subscribe confusion, which complicated any efforts to achieve a workable solution. However, we now have a solution with that out of the way. :fire: + +This feature has been designed with the following use cases in mind: + +- Broker-based messaging with well-defined response topic + "correlationId". +- Broker-based messaging with per process individual inbox aka "replyTopic" + "correlationId". +- Broker-based messaging with a temporary reply topic for an individual response. +- WebSocket, which has no topics, where the channel is a TCP connection where messages flow. + +``` +... +action: send | receive +reply: + address: + location: '$message.header#/replyTo' + channel: + $ref: '#/channels/userSignupReply' + messages: + - $ref: '#/components/messages/userSignedUpReply' +``` + +Read more about the [Operation Reply Object here](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationReplyObject). + +| Issue(s) | PR(s) | +| ----------- | ----------- | +| [#94](https://github.com/asyncapi/spec/issues/94), [#558](https://github.com/asyncapi/spec/issues/558) | [#847](https://github.com/asyncapi/spec/pull/847) | + +### Optional channels +We have seen many use cases where an AsyncAPI document has been used as a form of menu or collection of definitions. To do this in v2 would require a bit of a hack. But in v3, channels are now entirely optional. This means that it's now possible to have a valid AsyncAPI document as such: + +``` +asyncapi: 3.0.0 +... +components: + ... +``` + +| Issue(s) | PR(s) | +| ----------- | ----------- | +| [#829](https://github.com/asyncapi/spec/issues/829) | [#847](https://github.com/asyncapi/spec/pull/847) | + +### Unified referencing behaviors + +In v2, there were two instances where we used implicit references; server security configuration, by name referencing security requirement object in components, for channels to reference global servers by name. To stay as consistent as possible, we wanted to unify how references were used, which means that in v3, we ONLY use explicit references. + +The `scopes` information in the [Security Schema Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#securitySchemeObject) is also now an array instead of an object. + +``` +asyncapi: 3.0.0 +... +servers: + SomeServer: + security: + - $ref: '#/components/securitySchemes/SomeSecurity' +channels: + SomeChannel: + servers: + - $ref: '#/servers/SomeServer' +components: + securitySchemes: + SomeSecurity: + ... + scopes: [...] +``` + +| Issue(s) | PR(s) | Migration Guide | +| ----------- | ----------- | ----------- | +| [#829](https://github.com/asyncapi/spec/issues/829) | [#852](https://github.com/asyncapi/spec/pull/852) | [Unifying explicit and implicit references](/docs/migration/migrating-to-v3#unifying-explicit-and-implicit-references) | + +### Common metadata fields +There has been some inconsistency between which metadata fields are available in the different objects. Now we have added a few extra fields: +- added `title`, `summary`, and `externalDocs` fields in the [Server Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject) +- added `title` and `summary` fields in the [Channel Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#channelObject) +- added `title` field in the [Operation Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject) and [Operation Trait Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationTraitObject) + +``` +asyncapi: 3.0.0 +... +servers: + SomeServer: + title: Some Server title + summary: This some server is for something + externalDocs: + ... +channels: + SomeChannel: + title: Some channel title + summary: Some channel summary +operations: + SomeOperation: + title: Some operation title + traits: + - title: Some operation traits title +``` + +| Issue(s) | PR(s) | +| ----------- | ----------- | +| [#795](https://github.com/asyncapi/spec/issues/795) | [#796](https://github.com/asyncapi/spec/pull/796) | + +### Cleaning up the root object +There was two meta information lingering in the root of the AsyncAPI object, which did not make much sense since we have the `info` object for all the meta information. + +Therefore the root `tags` and `externalDocs` have been moved to the [Info Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#infoObject). + +``` +asyncapi: 3.0.0 +... +info: + ... + externalDocs: + description: Find more info here + url: https://www.asyncapi.org + tags: + - name: e-commerce +... +``` + +| PR(s) | Migration Guide | +| ----------- | ----------- | +| [#794](https://github.com/asyncapi/spec/pull/794) | [Moved metadata](/docs/migration/migrating-to-v3#moved-metadata) | + +### Splitting out server URL into host and pathname +There has been some confusion about what the `url` of a server should contain; is it both protocol + host + path? What about the protocol field, then? Therefore each field now has its field for the host, path, and protocol in the [Server Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject). + +``` +asyncapi: 3.0.0 +... +servers: + localhost: + host: localhost + path: /api/v1, + protocol: mqtt +``` + +| Issue(s) | PR(s) | Migration Guide | +| ----------- | ----------- | ----------- | +| [#547](https://github.com/asyncapi/spec/issues/547), [#274](https://github.com/asyncapi/spec/issues/274) | [#888](https://github.com/asyncapi/spec/pull/888) | [Server URL splitting up](/docs/migration/migrating-to-v3#server-url-splitting-up) | + +### More reusable objects in components +This is a bit of a mixture between some of the features, that all added a little to this. It's now possible to add more stuff under the [Components Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#componentsObject): +- Replies +- Reply addresses +- Tags +- External docs +- Operations +- Channels + +``` +asyncapi: 3.0.0 +... +components: + ... + replies: + ... + replyAddresses: + ... + tags: + ... + externalDocs: + ... + operations: + ... + channels: + ... +``` + +| Issue(s) | PR(s) | +| ----------- | ----------- | +| [#829](https://github.com/asyncapi/spec/issues/829) | [#847](https://github.com/asyncapi/spec/pull/847), [#792](https://github.com/asyncapi/spec/pull/792), [#806](https://github.com/asyncapi/spec/pull/806), [#827](https://github.com/asyncapi/spec/pull/827) | + +### New trait behavior +Traits in v2 always replaced any duplicate properties that were defined both in traits and the associated object. This meant, for example, if the message traits defined headers and the message object did as well, only the message trait headers would be applied because it overwrote anything you wrote in the message object. + +In v3, this has now been changed so that [a property on a trait MUST NOT override the same property on the target object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#traitsMergeMechanism). + +For example, take a look at this message: +``` +messageId: userSignup +description: A longer description. +payload: + $ref: '#/components/schemas/userSignupPayload' +traits: + - name: UserSignup + title: User signup + summary: Action to sign a user up. + description: Description from trait. +``` +Take notice of how `description` is not overwritten by the traits: + +``` +messageId: userSignup +name: UserSignup +title: User signup +summary: Action to sign a user up. +description: A longer description. # it's still description from "main" object +payload: + $ref: '#/components/schemas/userSignupPayload' +``` + +| Issue(s) | PR(s) | Migration Guide | +| ----------- | ----------- | ----------- | +| [#505](https://github.com/asyncapi/spec/issues/505) | [#517](https://github.com/asyncapi/spec/pull/517), [#532](https://github.com/asyncapi/spec/pull/532), [#907](https://github.com/asyncapi/spec/pull/907) | [New trait behavior](/docs/migration/migrating-to-v3#new-trait-behavior) | + + +### Schema format and payload definition +With schemas, one thing that has always been impossible was reusing schemas with different schema formats. That's because the schema format information is part of the message object. That means that if you reference a Schema object, it has no information about the schema format because it's not located together. + +In v3, schemaFormat has been removed from the [Message Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#messageObject) and [Message Trait Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#messageTraitObject), and a new [schema Object called `Multi Format Schema Object`](https://www.asyncapi.com/docs/reference/specification/v3.0.0#multiFormatSchemaObject) has been introduced, which pairs a schema together with its schema format. Which now enables much better reusability: + +``` +asyncapi: 3.0.0 +... +components: + schemas: + avroSchema: + schemaFormat: 'application/vnd.apache.avro+yaml;version=1.9.0' + schema: + type: record + name: User + namespace: com.company + doc: User information + fields: + - name: displayName + type: string +``` + +| Issue(s) | PR(s) | Migration Guide | +| ----------- | ----------- | ----------- | +| [#622](https://github.com/asyncapi/spec/issues/622) | [#797](https://github.com/asyncapi/spec/pull/797), [#910](https://github.com/asyncapi/spec/pull/910) | [Schema format and schemas](/docs/migration/migrating-to-v3#schema-format-and-schemas) | + +### Simplified Parameters +In v2, it was possible to use the full power of JSON Schema to define parameters, however, it introduced a lot of complexity to parameters, so for v3 it was dialed way down to only allow a very small set of properties. + +In v3, the new [Parameter object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#parameterObject) can now only have the following properties: `enum`, `default`, `description`, `examples`, and `location`. + +``` +asyncapi: 3.0.0 +... +channels: + userSignup: + address: user/{userId}/signedup + parameters: + userId: + description: Id of the user. +``` + +By default this means that any parameter is of type `string`. + +| Issue(s) | PR(s) | Migration Guide | +| ----------- | ----------- | ----------- | +| [#583](https://github.com/asyncapi/spec/issues/583) | [#935](https://github.com/asyncapi/spec/pull/935) | [Restricted parameters object](/docs/migration/migrating-to-v3#restricted-parameters-object) | + +### 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. + +## Acknowledgements +Spec 3.0 have been a massive undertaking, so I would like to say a huge "thank you!" to everyone who has been involved; maybe you commented on your views, added to discussions, joined the live meetings, championed changes, or reviewed proposed changes; this section is for you! + +Thank you, [Simon Heimler](https://github.com/Fannon), [Vladimír Gorej](https://github.com/char0n), [Fran Méndez](https://github.com/fmvilas), [Lukasz Gornicki](https://github.com/derberg), [Sergio Moya](https://github.com/smoya), [Michael Davis](https://github.com/damaru-inc), [Maciej Urbańczyk](https://github.com/magicmatatjahu), [Jesse Menning](https://github.com/jessemenning), [Heiko Henning](https://github.com/GreenRover), [Gerald Loeffler ](https://github.com/GeraldLoeffler), [c-pius](https://github.com/c-pius), [Ian Cooper](https://github.com/iancooper), [Dale Lane](https://github.com/dalelane), [Jörg Walter](https://github.com/joerg-walter-de), [Nic Townsend](https://github.com/nictownsend), [Laurent Broudoux](https://github.com/lbroudoux), [olamiral](https://github.com/olamiral), [Iván García Sainz-Aja](https://github.com/ivangsa), [Fabian Bühler](https://github.com/buehlefs), [John Fallows](https://github.com/jfallows), [Adrian Hope-Bailie](https://github.com/adrianhopebailie), [Christian (prdatur)](https://github.com/prdatur), [Karl Morrison](https://github.com/basickarl), [Javier Jiménez Roda](https://github.com/jjimenezroda), [Marek Sebera](https://github.com/smarek), [Nathanaël Lécaudé](https://github.com/natcl), [Jeremy Whitlock](https://github.com/whitlockjc), [souvik](https://github.com/Souvikns), [Animesh Kumar](https://www.github.com/animeshkumar923), [Samir AMZANI](https://github.com/Amzani), [Alejandra Quetzalli](https://github.com/alequetzalli), [Vaishnavi](https://github.com/VaishnaviNandakumar), [Mahfuza](https://github.com/mhmohona), [Bhaswati](https://github.com/BhaswatiRoy), [Cynthia Peter](https://github.com/CynthiaPeter), [Arya Gupta](https://github.com/Arya-Gupta), [Joy Almeida](https://github.com/J0SAL), [Hridyesh](https://github.com/kakabisht), [Rohit](https://github.com/TRohit20), [Ashish Padhy](https://github.com/Shurtu-gal), [Al Amin Muhammad](https://github.com/alaminthespecial), [nickshoe](https://github.com/nickshoe), [Khuda Dad Nomani](https://github.com/KhudaDad414), [V Thulisile Sibanda](https://github.com/thulieblack), [Ace](https://github.com/AceTheCreator), [Mihael Bosnjak](https://github.com/mboss37), [Sambhav Gupta](https://github.com/sambhavgupta0705), [Jonas Lagoni](https://github.com/jonaslagoni), [Afzal Ansari](https://github.com/afzal442) \ No newline at end of file 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/concepts/application.md b/pages/docs/concepts/application.md index 6de5af6d829..1d9c4634a94 100644 --- a/pages/docs/concepts/application.md +++ b/pages/docs/concepts/application.md @@ -21,7 +21,3 @@ flowchart TD D --> F[CONSUMER application] ``` The above diagram describes a message communication traveling through a channel between a **PRODUCER application** and a **CONSUMER application**. - - -When writing your AsyncAPI document, make sure to describe what a user can do with your application; not what the application does. In other words, if your application is a producer, your AsyncAPI document should describe where users can subscribe to, to receive messages produced by your producer application. - 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/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. 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' +``` 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..2463c8d8d97 --- /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 your server is secured with the `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 an API key or a username and password. + +Here is an example of adding security to your server, demonstrating that different servers can employ various 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 an 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, it is a good practice 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 depends on other factors such as the protocol used, use case, business perspective, and more. Additionally, you can also [add security at the `operation` level](securing-operations). 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' +``` diff --git a/pages/docs/concepts/asyncapi-document/tags.md b/pages/docs/concepts/asyncapi-document/tags.md new file mode 100644 index 00000000000..5b2c4c348d5 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/tags.md @@ -0,0 +1,335 @@ +--- +title: 'Tags' +weight: 63 +--- + +A tag functions as a label or category for logically grouping related entities like channels or servers in an event-driven system. The `tag` object facilitates the organization of channels, operations, or other components, categorizing them based on functionality, purpose, or other relevant criteria. + +In AyncAPI, the `tags` object is a list of individual `tag` objects. Each `tag` within this collection can be defined with a specific name, accompanied by an optional description that offers additional insight into the tag's intended purpose or usage. + +You can define `tags` in the [`components` object](/docs/reference/specification/latest#componentsObject) of an AsyncAPI document, which enables the reusability of the tags. If you include `tags` in the `components` object, they can be re-used by using [reference objects](/docs/reference/specification/latest#referenceObject). + +Additionally, within AsyncAPI, you can create a list of tags in the `tags` object at the `info` level, specifying the tags you intend to use throughout the document. These predefined tags can then be applied to individual components like `servers` or `channels`, facilitating logical grouping and organization of these components. + +## `tags` in AsyncAPI document + +The `tags` object consists of a list of `tag` objects, which can be referenced using the [reference object](/docs/reference/specification/latest#referenceObject). + +The `tags` object is a list of tags and individual `tag` objects, each containing specific fields. + +In an AsyncAPI document, the function of tags within the `tags` object differs depending on context. For example, the `tags` object can be employed for consistent usage of tags across the document and logical grouping of components. Alternatively, tags can be applied to individual components such as `servers` or `channels`, serving more specific purposes within those contexts. + +The `tags` object fields include: +- `name`: The name of the tag. +- `description`: A short description for the tag. +- `externalDocs`: Additional external documentation for the tag. + +### `tags` in `info` object + +When specified in the `tags` property of the info object, tags offer a comprehensive categorization for the entire AsyncAPI document. These globally defined tags under the `info` object impart an overarching context, representing key themes or functional areas within the event-driven system. They effectively group elements like channels or servers by their broader relevance, providing a holistic understanding of the application's structure. + +Here's a visual representation of the `tags` object inside an `info` object in an AsyncAPI document: +```mermaid +graph LR + B[info] + B --> C[title] + B --> D[version] + B --> F[tags] + F --> G[name] + F --> I[description] + F --> K[externalDocs] + + + style B fill:#47BCEE,stroke:#000; + style F fill:#47BCEE,stroke:#000; + style I fill:#47BCEE,stroke:#000; + style K fill:#47BCEE,stroke:#000; + style G fill:#47BCEE,stroke:#000; +``` + +Below is an example of the `tags` object inside the `info` object in an AsyncAPI document: +```yaml +asyncapi: 3.0.0 +info: + title: AsyncAPI Documentation + version: 1.0.0 + description: | + This AsyncAPI document provides an overview + of the event-driven system. + tags: + - name: Applications + description: All applications related topics. + externalDocs: + description: More info about applications + url: https://applications.example.com/docs + - name: Time + description: All time related topics. + externalDocs: + description: More info about time + url: https://time.example.com/docs +``` + +### `tags` in `servers` object +When tags are utilized within the `servers` object's `tags` property, they specifically pertain to server configurations and characteristics. These tags enable server categorization by various criteria, including geographical location, environment type (i.e., production or development), or unique server features. Using `tags` in the `servers` object allows for the categorization and organization of servers based on specific tags or labels. Using the `tags` object under the `servers` object is optional. + +Here's a visual representation of the `tags` object inside a `servers` object in an AsyncAPI document: +```mermaid +graph LR + B[servers] + B --> C[host] + B --> E[protocol] + B --> G[tags] + G --> H[name] + G --> I[description] + G --> J[externalDocs] + style B fill:#47BCEE,stroke:#000; + style G fill:#47BCEE,stroke:#000; + style I fill:#47BCEE,stroke:#000; + style H fill:#47BCEE,stroke:#000; + style J fill:#47BCEE,stroke:#000; +``` + +Below is an example of the `tags` object inside the `servers` object in an AsyncAPI document: +```yaml +asyncapi: 3.0.0 + +info: + title: AsyncAPI Documentation + version: 1.0.0 + +servers: + development: + host: localhost:5672 + description: Development AMQP broker. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:development" + description: "This environment is meant for developers to run their tests." + production: + host: rabbitmq.in.mycompany.com:5672 + description: RabbitMQ broker for the production environment. + protocol: amqp + protocolVersion: 0-9-1 + tags: + - name: "env:production" + description: "This environment is the live environment available for final users." +``` + +### `tags` in `channels` object + +Tags linked with individual channels enable logical grouping and categorization based on specific functionalities or business domains. When the `tags` object is used within a `channels` object in an AsyncAPI document, its context is either confined to the `channels` object, impacting only that section, or it can be employed for consistent tagging across the document for cohesive grouping. Using the `tags` object under the `channels` object is optional. + + +Here's a visual representation of the `tags` object inside a `channels` object in an AsyncAPI document: +```mermaid +graph LR + A[channel] + B(address) + E(messages) + P(tags) + F(name) + G(description) + I(externalDocs) + + A --> B + A --> E + A --> P + P --> F + P --> G + P --> I + style A fill:#47BCEE,stroke:#000; + style P fill:#47BCEE,stroke:#000; + style F fill:#47BCEE,stroke:#000; + style G fill:#47BCEE,stroke:#000; + style I fill:#47BCEE,stroke:#000; +``` + +Below is an example of the `tags` object inside the `channels` object in an AsyncAPI document: +```yaml +asyncapi: 3.0.0 + +info: + title: AsyncAPI Documentation + version: 1.0.0 + +channels: + SignedUp: + address: 'user.signedup' + messages: + userSignedUp: + payload: + type: object + tags: + - name: user + description: User-related messages +``` + +### `tags` in `operations` object + +Within an AsyncAPI document, the `tags` object in the `operations` object facilitates logical grouping and categorization of `operation` objects by operation type, functionality, and more. When used in an `operations` object, the `tags` can either serve a specific purpose within that object or be employed for consistent, logical grouping of components across the document. Using the `tags` object in the `operations` object is optional. + +Here's a visual representation of the `tags` object inside a `operations` object in an AsyncAPI document: +```mermaid +graph LR + A[operation] + E(channel) + F(action) + H(tags) + X(name) + Y(description) + Z(externalDocs) + + A --> E + A --> F + A --> H + H --> X + H --> Y + H --> Z + style A fill:#47BCEE,stroke:#000; + style Z fill:#47BCEE,stroke:#000; + style H fill:#47BCEE,stroke:#000; + style Y fill:#47BCEE,stroke:#000; + style X fill:#47BCEE,stroke:#000; +``` + +Below is an example of the `tags` object inside the `operations` object in an AsyncAPI document: +```yaml +operations: + onUserSignUp: + title: User sign up + summary: Action to sign a user up. + description: A longer description + channel: + $ref: '#/channels/userSignup' + action: send + tags: + - name: user + description: operation related to user + - name: signup + description: operation related to a user's signUp + - name: register + description: operation related to a new registration + bindings: + amqp: + ack: false + traits: + - $ref: '#/components/operationTraits/kafka' +``` + +### `tags` in `message` object + +Tags linked to individual message objects in an AsyncAPI document enable logical grouping and categorization of messages based on specific criteria, requirements, channels, and operations. When implemented within a `message` object, the context of the `tags` object can be confined to that specific message or integrated as the strategy for consistent tagging and logical organization across the entire document. + +Here's a visual representation of a `tags` object inside a `message` object in an AsyncAPI document: +```mermaid +graph LR + A[message] --> B[summary] + A --> C[tags] + C --> D[name] + C --> E[description] + A --> F[headers] + A --> I[payload] + C --> Y[externalDocs] + style A fill:#47BCEE,stroke:#000; + style D fill:#47BCEE,stroke:#000; + style C fill:#47BCEE,stroke:#000; + style E fill:#47BCEE,stroke:#000; + style Y fill:#47BCEE,stroke:#000; +``` + +Below is an example of the `tags` object inside the `message` object in an AsyncAPI document: +```yaml + name: SimpleSignup +summary: A simple UserSignup example message +tags: + - name: userSignUp + description: some message related to user signup +headers: + correlationId: my-correlation-id + applicationInstanceId: myInstanceId +payload: + user: + someUserKey: someUserValue + signup: + someSignupKey: someSignupValue +``` + + +Here's an example illustrating all the tags being defined in the `components` object and then referenced in other components such as `servers`, `channels`, and more: + +```yml +asyncapi: 3.0.0 + +components: + tags: + speech: + name: Speech + description: All speech related topics. + video: + name: Video + description: All video related topics. + +info: + title: AsyncAPI Documentation + version: 1.0.0 + description: | + This AsyncAPI document provides an overview + of the event-driven system. + tags: + - $ref: '#/components/tags/speech' + - $ref: '#/components/tags/video' + +servers: + speech: + host: localhost:5672 + description: RabbitMQ broker for sending speech data. + protocol: amqp + tags: + - $ref: '#/components/tags/speech' + video: + host: localhost:5673 + description: RabbitMQ broker for video information. + protocol: amqp + tags: + - $ref: '#/components/tags/video' + +channels: + getSpeech: + address: 'application/speech/get' + servers: + - $ref: '#/servers/speech' + messages: + voice: + name: Voice + summary: Add info about the voice stream data. + tags: + - $ref: '#/components/tags/speech' + getVideo: + address: 'application/video/get' + servers: + - $ref: '#/servers/video' + messages: + voice: + name: Video + summary: Add info about the video data live bitrate and others. + tags: + - $ref: '#/components/tags/video' + +operations: + onVoiceStreamed: + title: Get speech data + channel: + $ref: '#/channels/getSpeech' + action: receive + tags: + - $ref: '#/components/tags/speech' + + onVideoStreamed: + title: Get video data + channel: + $ref: '#/channels/getVideo' + action: receive + tags: + - $ref: '#/components/tags/video' +``` diff --git a/pages/docs/guides/message-validation.md b/pages/docs/guides/message-validation.md index 01da64066c0..29ea985b947 100644 --- a/pages/docs/guides/message-validation.md +++ b/pages/docs/guides/message-validation.md @@ -85,17 +85,26 @@ With the Schema Registry in place, the producer first talks to the Schema Regist 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: 2.6.0 +asyncapi: 3.0.0 info: title: Example with Avro version: 0.1.0 + channels: example: - publish: - message: - schemaFormat: 'application/vnd.apache.avro;version=1.9.0' + address: 'example' + messages: + avroMessage: payload: - $ref: 'https://example.europe-west3.gcp.confluent.cloud/subjects/test/versions/1/schema' + 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' ``` --- diff --git a/pages/docs/guides/validate.md b/pages/docs/guides/validate.md index 96b3505df66..a17ccf35bf7 100644 --- a/pages/docs/guides/validate.md +++ b/pages/docs/guides/validate.md @@ -5,7 +5,7 @@ weight: 120 --- ## Introduction -This guide teaches multiple ways to validate AsyncAPI documents. +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: @@ -51,7 +51,7 @@ Let's discuss an example. While the `summary` property is optional in an AsyncAP -One way this can be done is by using **Spectral**, an API linting tool which has a built-in [custom ruleset properties](https://meta.stoplight.io/docs/spectral/e5b9616d6d50c-custom-rulesets) with [AsyncAPI rules](https://meta.stoplight.io/docs/spectral/1e63ffd0220f3-async-api-rules) for the AsyncAPI specification. It also enables you to define company-specific rules that you can use internally. +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). @@ -59,8 +59,6 @@ To get started: Example: ```js { - "formats": ["asyncapi2"], - "extends": "spectral:asyncapi", "rules": { // add your own rules here } @@ -69,31 +67,24 @@ To get started: 3. Create and add your own custom ruleset: ```js - { - "formats": ["asyncapi2"], - "extends": "spectral:asyncapi", + { "rules": { - // add your own rules here - "valid-document-version": { - "message": "Version must match 2.x.x", - "severity": "hint", - "given": "$.info", - "then": [ - { - "field": "version", - "function": "defined" - }, - { - "field": "version", - "function": "pattern", - "functionOptions": { - "match": "^[0-9]+$" - } - } - ] - } + "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: 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..73f48d79494 --- /dev/null +++ b/pages/docs/migration/migrating-to-v3.md @@ -0,0 +1,443 @@ +--- +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 {Asyncapi3ChannelComparison, Asyncapi3IdAndAddressComparison, Asyncapi3MetaComparison, Asyncapi3OperationComparison,Asyncapi3SchemaFormatComparison, Asyncapi3ServerComparison, +Asyncapi3ParameterComparison} 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#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#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#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#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#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: + - messageId: UserMessage + ... + - messageId: UserMessage2 + ... + +asyncapi: 2.6.0 +... +channels: + user/signedup: + message: + messageId: UserMessage + ... +``` + +```yml +asyncapi: 3.0.0 +... +channels: + UserSignup: + address: user/signedup + messages: + UserMessage: + ... + UserMessage2: + ... + +asyncapi: 3.0.0 +... +channels: + UserSignup: + address: user/signedup + messages: + UserMessage: + ... +``` + +We have updated the structure of the Message Object by eliminating the `messageId` property. We now use the ID of the Message Object itself as the key in the key/value pairing, rendering a separate `messageId` property redundant. + +## 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#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#securitySchemeObject). + +```yml +asyncapi: 2.6.0 +servers: + production: + ... + security: + oauth_test: ["write:pets"] +... +channels: + test/path: + 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' +``` + +```yml +asyncapi: 3.0.0 +servers: + production: + ... + security: + - $ref: "#/components/securitySchemes/oauth_test" +... +channels: + test/path: + servers: + - $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#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 +... +``` + +## Restricted parameters object + +Parameters have often prioritized convenience over accurately reflecting real-world use cases. + + + +In v2, we significantly streamlined the Schema Object. While the previous version offered full capability with numerous, often underutilized options, it posed challenges in serializing objects or booleans in the channel path. + +The new v3 simplifies this by consistently using the string type and limiting available properties. Now, you can only access `enum`, `default`, `description`, `examples`, and `location`, ensuring a more focused and practical approach." + +```yml +asyncapi: 2.6.0 +... +channels: + user/{user_id}/signedup: + parameters: + location: "$message.payload" + description: Just a test description + schema: + type: string + enum: ["test"] + default: "test" + examples: ["test"] + ... +``` + +```yml +asyncapi: 3.0.0 +... +channels: + userSignedUp: + address: user/{user_id}/signedup + parameters: + user_id: + enum: ["test"] + default: "test" + description: Just a test description + examples: ["test"] + location: "$message.payload" +``` 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 1e1364f7b81..00000000000 --- a/pages/docs/reference/specification/v2.6.0.md +++ /dev/null @@ -1,2497 +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:** Using the $ref property with other properties is deprecated since the 2.3.0 version of the specification. -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: - -```plaintext -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 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: - -```plaintext - 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.15.md b/pages/docs/reference/specification/v3.0.0.md similarity index 95% rename from pages/docs/reference/specification/v3.0.0-next-major-spec.15.md rename to pages/docs/reference/specification/v3.0.0.md index 7685ac566d6..a34d83190e8 100644 --- a/pages/docs/reference/specification/v3.0.0-next-major-spec.15.md +++ b/pages/docs/reference/specification/v3.0.0.md @@ -1,7 +1,3 @@ -# ATTENTION: Work in progress - -This version is not yet ready to be used. We're currently working on it. If you want to join the effort and participate in the development of the next major version of AsyncAPI, head over to [GitHub Issue that we use for tracking 3.0 development progress](https://github.com/asyncapi/spec/issues/691). - # AsyncAPI Specification #### Attribution @@ -64,7 +60,6 @@ operations: Aside from the issues mentioned above, there may also be infrastructure configuration that is not represented here. For instance, a system may use a read-only channel for receiving messages, a different one for sending them, and an intermediary process that will forward messages from one channel to the other. - ## Definitions ### Server @@ -80,13 +75,13 @@ A sender is a type of application, that is sending [messages](#definitionsMessag A receiver is a type of application that is receiving [messages](#definitionsMessage) from [channels](#definitionsChannel). A receiver MAY receive from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. A receiver MAY forward a received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and forwards them. ### Message -A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message 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. +A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MAY contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. ### Channel A channel is an addressable component, made available by the [server](#definitionsServer), for the organization of [messages](#definitionsMessage). [Sender](#definitionsSender) applications send messages to channels and [receiver](#definitionsReceiver) applications receive messages from channels. [Servers](#definitionsServer) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#definitionsServer) implementation, the channel MAY be included in the message via protocol-defined headers. ### Protocol -A protocol is the mechanism (wireline protocol or API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket. +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. @@ -573,12 +568,12 @@ Describes a shared communication channel. Field Name | Type | Description ---|:---:|--- -address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions). +address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions). Query parameters and fragments SHALL NOT be used, instead use [bindings](#channelBindingsObject) to define them. messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#messageObject) defined in this map.** title | `string` | A human-friendly title for the channel. summary | `string` | A short summary of the channel. description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -servers | [[Reference Object](#referenceObject)] | An array of `$ref` pointers to the definition of the servers in which this channel is available. If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#serverObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +servers | [[Reference Object](#referenceObject)] | An array of `$ref` pointers to the definition of the servers in which this channel is available. If the channel is located in the [root Channels Object](#channelsObject), it MUST point to a subset of server definitions located in the [root Servers Object](#serversObject), and MUST NOT point to a subset of server definitions located in the [Components Object](#componentsObject) or anywhere else. If the channel is located in the [Components Object](#componentsObject), it MAY point to a [Server Objects](#serverObject) in any location. If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#serverObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](#channelAddressExpressions). tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this channel. @@ -774,7 +769,7 @@ Describes a specific operation. Field Name | Type | Description ---|:---:|--- action | `"send"` | `"receive"` | **Required**. Use `send` when it's expected that the application will send a message to the given [`channel`](#operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#operationObjectChannel). -channel | [Reference Object](#referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +channel | [Reference Object](#referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. If the operation is located in the [root Operations Object](#operationsObject), it MUST point to a channel definition located in the [root Channels Object](#channelsObject), and MUST NOT point to a channel definition located in the [Components Object](#componentsObject) or anywhere else. If the operation is located in the [Components Object](#componentsObject), it MAY point to a [Channel Object](#channelObject) in any location. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. title | `string` | A human-friendly title for the operation. summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. @@ -783,7 +778,7 @@ Field Name | Type | Description externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this operation. bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. traits | [[Operation Trait Object](#operationTraitObject) | [Reference Object](#referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged using [traits merge mechanism](#traits-merge-mechanism). The resulting object MUST be a valid [Operation Object](#operationObject). -messages | [[Reference Object](#referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#messageObject) that can be processed by this operation. It MUST contain a subset of the messages defined in the [channel referenced in this operation](#operationObjectChannel). **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#messageObject) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain [Message Objects](#messageObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +messages | [[Reference Object](#referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#messageObject) that can be processed by this operation. It MUST contain a subset of the messages defined in the [channel referenced in this operation](#operationObjectChannel), and MUST NOT point to a subset of message definitions located in the [Messages Object](#componentsMessages) in the [Components Object](#componentsObject) or anywhere else. **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#messageObject) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain [Message Objects](#messageObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. reply | [Operation Reply Object](#operationReplyObject) | [Reference Object](#referenceObject) | The definition of the reply in a request-reply operation. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -921,8 +916,8 @@ Describes the reply part that MAY be applied to an Operation Object. If an opera Field Name | Type | Description ---|:---:|--- address | [Operation Reply Address Object](#operationReplyAddressObject) | [Reference Object](#referenceObject) | Definition of the address that implementations MUST use for the reply. -channel | [Reference Object](#referenceObject) | A `$ref` pointer to the definition of the channel in which this operation is performed. When [address](#operationReplyAddressObject) is specified, the [`address` property](#channelObjectAddress) of the channel referenced by this property MUST be either `null` or not defined. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. -messages | [[Reference Object](#referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#messageObject) that can be processed by this operation as reply. It MUST contain a subset of the messages defined in the [channel referenced in this operation reply](#operationObjectChannel). **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#messageObject) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain [Message Objects](#messageObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +channel | [Reference Object](#referenceObject) | A `$ref` pointer to the definition of the channel in which this operation is performed. When [address](#operationReplyAddressObject) is specified, the [`address` property](#channelObjectAddress) of the channel referenced by this property MUST be either `null` or not defined. If the operation reply is located inside a [root Operation Object](#operationObject), it MUST point to a channel definition located in the [root Channels Object](#channelsObject), and MUST NOT point to a channel definition located in the [Components Object](#componentsObject) or anywhere else. If the operation reply is located inside an [Operation Object] in the [Components Object](#componentsObject) or in the [Replies Object](#componentsReplies) in the [Components Object](#componentsObject), it MAY point to a [Channel Object](#channelObject) in any location. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +messages | [[Reference Object](#referenceObject)] | A list of `$ref` pointers pointing to the supported [Message Objects](#messageObject) that can be processed by this operation as reply. It MUST contain a subset of the messages defined in the [channel referenced in this operation reply](#operationObjectChannel), and MUST NOT point to a subset of message definitions located in the [Components Object](#componentsObject) or anywhere else. **Every message processed by this operation MUST be valid against one, and only one, of the [message objects](#messageObject) referenced in this list.** Please note the `messages` property value MUST be a list of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain [Message Objects](#messageObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1060,6 +1055,7 @@ Field Name | Type | Description `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). @@ -1091,6 +1087,7 @@ Field Name | Type | Description `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). @@ -1122,6 +1119,7 @@ Field Name | Type | Description `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). @@ -1154,6 +1152,7 @@ Field Name | Type | Description `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). @@ -1529,7 +1528,7 @@ Field Name | Type | Description schemas | Map[`string`, [Multi Format Schema Object](#multiFormatSchemaObject) \| [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Object](#schemaObject). If this is a [Schema Object](#schemaObject), then the `schemaFormat` will be assumed to be "application/vnd.aai.asyncapi+json;version=`asyncapi`" where the version is equal to the [AsyncAPI Version String](#A2SVersionString). servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject). channels | Map[`string`, [Channel Object](#channelObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Objects](#channelObject). - operations | Map[`string`, [Operation Item Object](#operationObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Item Objects](#operationObject). + operations | Map[`string`, [Operation Object](#operationObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Objects](#operationObject). messages | Map[`string`, [Message Object](#messageObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Objects](#messageObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). @@ -1887,7 +1886,7 @@ While composition offers model extensibility, it does not imply a hierarchy betw 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. +There are two ways to define the value of a discriminator for an inheriting instance. - Use the schema's name. - Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. diff --git a/pages/docs/tools/cli/usage.md b/pages/docs/tools/cli/usage.md index 4dc6cc33929..f3ec3010258 100644 --- a/pages/docs/tools/cli/usage.md +++ b/pages/docs/tools/cli/usage.md @@ -29,7 +29,7 @@ $ npm install -g @asyncapi/cli $ asyncapi COMMAND running command... $ asyncapi (--version) -@asyncapi/cli/0.59.2 linux-x64 node-v18.18.2 +@asyncapi/cli/1.2.8 linux-x64 node-v18.18.2 $ asyncapi --help [COMMAND] USAGE $ asyncapi COMMAND @@ -93,7 +93,7 @@ EXAMPLES $ asyncapi bundle ./asyncapi.yaml ./features.yaml --base ./asyncapi.yaml --reference-into-components ``` -_See code: [src/commands/bundle.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/bundle.ts)_ +_See code: [src/commands/bundle.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/bundle.ts)_ ## `asyncapi config` @@ -107,7 +107,7 @@ DESCRIPTION CLI config settings ``` -_See code: [src/commands/config/index.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/config/index.ts)_ +_See code: [src/commands/config/index.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/config/index.ts)_ ## `asyncapi config context` @@ -121,7 +121,7 @@ DESCRIPTION Manage short aliases for full paths to AsyncAPI documents ``` -_See code: [src/commands/config/context/index.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/config/context/index.ts)_ +_See code: [src/commands/config/context/index.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/config/context/index.ts)_ ## `asyncapi config context add CONTEXT-NAME SPEC-FILE-PATH` @@ -143,7 +143,7 @@ DESCRIPTION Add a context to the store ``` -_See code: [src/commands/config/context/add.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/config/context/add.ts)_ +_See code: [src/commands/config/context/add.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/config/context/add.ts)_ ## `asyncapi config context current` @@ -160,7 +160,7 @@ DESCRIPTION Shows the current context that is being used ``` -_See code: [src/commands/config/context/current.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/config/context/current.ts)_ +_See code: [src/commands/config/context/current.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/config/context/current.ts)_ ## `asyncapi config context edit CONTEXT-NAME NEW-SPEC-FILE-PATH` @@ -181,7 +181,7 @@ DESCRIPTION Edit a context in the store ``` -_See code: [src/commands/config/context/edit.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/config/context/edit.ts)_ +_See code: [src/commands/config/context/edit.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/config/context/edit.ts)_ ## `asyncapi config context init [CONTEXT-FILE-PATH]` @@ -204,7 +204,7 @@ DESCRIPTION Initialize context ``` -_See code: [src/commands/config/context/init.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/config/context/init.ts)_ +_See code: [src/commands/config/context/init.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/config/context/init.ts)_ ## `asyncapi config context list` @@ -221,7 +221,7 @@ DESCRIPTION List all the stored contexts in the store ``` -_See code: [src/commands/config/context/list.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/config/context/list.ts)_ +_See code: [src/commands/config/context/list.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/config/context/list.ts)_ ## `asyncapi config context remove CONTEXT-NAME` @@ -241,7 +241,7 @@ DESCRIPTION Delete a context from the store ``` -_See code: [src/commands/config/context/remove.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/config/context/remove.ts)_ +_See code: [src/commands/config/context/remove.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/config/context/remove.ts)_ ## `asyncapi config context use CONTEXT-NAME` @@ -261,7 +261,7 @@ DESCRIPTION Set a context as current ``` -_See code: [src/commands/config/context/use.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/config/context/use.ts)_ +_See code: [src/commands/config/context/use.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/config/context/use.ts)_ ## `asyncapi config versions` @@ -278,7 +278,7 @@ DESCRIPTION Show versions of AsyncAPI tools used ``` -_See code: [src/commands/config/versions.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/config/versions.ts)_ +_See code: [src/commands/config/versions.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/config/versions.ts)_ ## `asyncapi convert [SPEC-FILE]` @@ -300,7 +300,7 @@ DESCRIPTION Convert asyncapi documents older to newer versions ``` -_See code: [src/commands/convert.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/convert.ts)_ +_See code: [src/commands/convert.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/convert.ts)_ ## `asyncapi diff OLD NEW` @@ -355,7 +355,7 @@ DESCRIPTION Find diff between two asyncapi files ``` -_See code: [src/commands/diff.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/diff.ts)_ +_See code: [src/commands/diff.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/diff.ts)_ ## `asyncapi generate` @@ -369,7 +369,7 @@ DESCRIPTION Generate typed models or other things like clients, applications or docs using AsyncAPI Generator templates. ``` -_See code: [src/commands/generate/index.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/generate/index.ts)_ +_See code: [src/commands/generate/index.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/generate/index.ts)_ ## `asyncapi generate fromTemplate ASYNCAPI TEMPLATE` @@ -406,7 +406,7 @@ EXAMPLES $ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template --param version=1.0.0 singleFile=true --output ./docs --force-write ``` -_See code: [src/commands/generate/fromTemplate.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/generate/fromTemplate.ts)_ +_See code: [src/commands/generate/fromTemplate.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/generate/fromTemplate.ts)_ ## `asyncapi generate models LANGUAGE FILE` @@ -480,7 +480,7 @@ DESCRIPTION Generates typed models ``` -_See code: [src/commands/generate/models.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/generate/models.ts)_ +_See code: [src/commands/generate/models.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/generate/models.ts)_ ## `asyncapi new` @@ -535,7 +535,7 @@ EXAMPLES $ asyncapi new --file-name=my-asyncapi.yml --example=default-example.yml --no-tty - create a new file with a specific name, using one of the examples and without interactive mode ``` -_See code: [src/commands/new/index.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/new/index.ts)_ +_See code: [src/commands/new/index.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/new/index.ts)_ ## `asyncapi new file` @@ -590,7 +590,7 @@ EXAMPLES $ asyncapi new --file-name=my-asyncapi.yml --example=default-example.yml --no-tty - create a new file with a specific name, using one of the examples and without interactive mode ``` -_See code: [src/commands/new/file.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/new/file.ts)_ +_See code: [src/commands/new/file.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/new/file.ts)_ ## `asyncapi new glee` @@ -598,17 +598,18 @@ Creates a new Glee project ``` USAGE - $ asyncapi new glee [-h] [-n ] + $ asyncapi new glee [-h] [-n ] [-t ] FLAGS - -h, --help Show CLI help. - -n, --name= [default: project] name of the project + -h, --help Show CLI help. + -n, --name= [default: project] name of the project + -t, --template= [default: default] name of the template DESCRIPTION Creates a new Glee project ``` -_See code: [src/commands/new/glee.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/new/glee.ts)_ +_See code: [src/commands/new/glee.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/new/glee.ts)_ ## `asyncapi new project` @@ -616,17 +617,18 @@ Creates a new Glee project ``` USAGE - $ asyncapi new project [-h] [-n ] + $ asyncapi new project [-h] [-n ] [-t ] FLAGS - -h, --help Show CLI help. - -n, --name= [default: project] name of the project + -h, --help Show CLI help. + -n, --name= [default: project] name of the project + -t, --template= [default: default] name of the template DESCRIPTION Creates a new Glee project ``` -_See code: [src/commands/new/project.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/new/project.ts)_ +_See code: [src/commands/new/project.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/new/project.ts)_ ## `asyncapi optimize [SPEC-FILE]` @@ -662,7 +664,7 @@ EXAMPLES $ asyncapi optimize ./asyncapi.yaml --optimization=remove-components,reuse-components,move-to-components --output=terminal --no-tty ``` -_See code: [src/commands/optimize.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/optimize.ts)_ +_See code: [src/commands/optimize.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/optimize.ts)_ ## `asyncapi start` @@ -676,7 +678,7 @@ DESCRIPTION Start asyncapi studio ``` -_See code: [src/commands/start/index.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/start/index.ts)_ +_See code: [src/commands/start/index.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/start/index.ts)_ ## `asyncapi start studio` @@ -695,7 +697,7 @@ DESCRIPTION starts a new local instance of Studio ``` -_See code: [src/commands/start/studio.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/start/studio.ts)_ +_See code: [src/commands/start/studio.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/start/studio.ts)_ ## `asyncapi validate [SPEC-FILE]` @@ -722,5 +724,5 @@ DESCRIPTION validate asyncapi file ``` -_See code: [src/commands/validate.ts](https://github.com/asyncapi/cli/blob/v0.59.2/src/commands/validate.ts)_ +_See code: [src/commands/validate.ts](https://github.com/asyncapi/cli/blob/v1.2.8/src/commands/validate.ts)_ diff --git a/pages/docs/tools/generator/api.md b/pages/docs/tools/generator/api.md index b6923a5e7a1..edf7a82e4f9 100644 --- a/pages/docs/tools/generator/api.md +++ b/pages/docs/tools/generator/api.md @@ -238,7 +238,7 @@ Sets up the output configuration based on the specified output type. **Example** ```js const generator = new Generator(); -generator.setupOutput(); +await generator.setupOutput(); ``` diff --git a/pages/docs/tools/generator/asyncapi-document.md b/pages/docs/tools/generator/asyncapi-document.md index 82d1a7d717c..dfd2db6e854 100644 --- a/pages/docs/tools/generator/asyncapi-document.md +++ b/pages/docs/tools/generator/asyncapi-document.md @@ -19,7 +19,7 @@ In the following sections, you'll learn about the inner working of the generator 1. The **Generator** receives the **AsyncAPI Document** as input. 2. The **Generator** sends to the **[Parser](parser)** the **asyncapiString** is a stringified version of the original **AsyncAPI Document** to validate and parse it. 3. The **Parser** validates the **AsyncAPI Document** using additional schema-related plugins, either the OpenAPI schema, RAML data types, or Avro schema. -4. If the **Parser** determines that the **AsyncAPI Document** is valid, it manipulates the original JSON/YAML document and provides a set of helper functions in return, bundling them together into an **asyncapi** variable that is an instance of [**AsyncAPIDocument**](https://github.com/asyncapi/parser-js/blob/master/API.md#module_@asyncapi/parser+AsyncAPIDocument). +4. If the **Parser** determines that the **AsyncAPI Document** is valid, it manipulates the original JSON/YAML document and provides a set of helper functions in return, bundling them together into an **asyncapi** variable that is an instance of [**AsyncAPIDocument**](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#asyncapidocument). 5. At this point, the **Generator** passes the **originalAsyncAPI** and the **asyncapi** which make up part of the **[Template Context](template-context)** to the **Render Engine**. 6. The **Template Context** is accessible to the template files that are passed to either the [react](react-render-engine) or [nunjucks](nunjucks-render-engine) **Render Engines**. @@ -88,4 +88,4 @@ const apiName = asyncapi.info().title(); const channels = asyncapi.channels(); ``` -> To learn about the various instances you can use to access the documents' content, look at the API of the AsyncAPI JavaScript Parser and the structure of [AsyncAPIDocument](https://github.com/asyncapi/parser-js/blob/master/API.md#module_@asyncapi/parser+AsyncAPIDocument) +> To learn about the various instances you can use to access the documents' content, look at the API of the AsyncAPI JavaScript Parser and the structure of [AsyncAPIDocument](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#asyncapidocument) diff --git a/pages/docs/tools/generator/configuration-file.md b/pages/docs/tools/generator/configuration-file.md index f8ceb2635c0..0f37a3e921f 100644 --- a/pages/docs/tools/generator/configuration-file.md +++ b/pages/docs/tools/generator/configuration-file.md @@ -8,7 +8,7 @@ The `generator` property from `package.json` file must contain a JSON object tha |Name|Type|Description| |---|---|---| |`renderer`| String | Its value can be either `react` or `nunjucks` (default). -|`apiVersion`| String | Determines which **major** version of the [Parser-API](https://github.com/asyncapi/parser-api) the template uses. For example, `v2` for `v2.x.x`. If not specified, the Generator assumes the template is not compatible with the Parser-API so it will use the [Parser-JS v1 API](https://github.com/asyncapi/parser-js/tree/v1.18.1#api-documentation). For templates that need to support AsyncAPI specification v3 make sure to use `v2` [Parser-API](https://github.com/asyncapi/parser-api). If the template uses a version of the Parser-API that is not supported by the Generator, the Generator will throw an error. +|`apiVersion`| String | Determines which **major** version of the [Parser-API](https://github.com/asyncapi/parser-api) the template uses. For example, `v2` for `v2.x.x`. If not specified, the Generator assumes the template is not compatible with the Parser-API so it will use the [Parser-JS v1 API](https://github.com/asyncapi/parser-js/tree/v1.18.1#api-documentation). For templates that need to support AsyncAPI specification v3 make sure to use `v3` [Parser-API](https://github.com/asyncapi/parser-api). If the template uses a version of the Parser-API that is not supported by the Generator, the Generator will throw an error. |`supportedProtocols`| [String] | A list with all the protocols this template supports. |`parameters`| Object[String, Object] | An object with all the parameters that can be passed when generating the template. When using the command line, it's done by indicating `--param name=value` or `-p name=value`. |`parameters[param].description`| String | A user-friendly description about the parameter. @@ -28,7 +28,7 @@ The `generator` property from `package.json` file must contain a JSON object tha "generator": { "renderer": "react", - "apiVersion": "v2", + "apiVersion": "v3", "supportedProtocols": ["amqp", "mqtt"], "parameters": { "server": { diff --git a/pages/docs/tools/generator/file-templates.md b/pages/docs/tools/generator/file-templates.md index d84c7d3a37a..5ba4a9687d3 100644 --- a/pages/docs/tools/generator/file-templates.md +++ b/pages/docs/tools/generator/file-templates.md @@ -5,13 +5,13 @@ weight: 140 It is possible to generate files for each specific object in your AsyncAPI documentation. For example, you can specify a filename like `$$channel$$.js` to generate a file for each channel defined in your AsyncAPI. The following file-template names and extra variables in them are available: - - `$$channel$$`, within the template-file you have access to two variables [`channel`](https://github.com/asyncapi/parser-js/blob/master/API.md#Channel) and [`channelName`](https://github.com/asyncapi/parser-js/blob/master/API.md#AsyncAPIDocument+channels). Where the `channel` contains the current channel being rendered. - - `$$message$$`, within the template-file you have access to two variables [`message`](https://github.com/asyncapi/parser-js/blob/master/API.md#Message) and [`messageName`](https://github.com/asyncapi/parser-js/blob/master/API.md#Message+uid). Where `message` contains the current message being rendered. - - `$$schema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-js/blob/master/API.md#Schema) and [`schemaName`](https://github.com/asyncapi/parser-js/blob/master/API.md#Schema+uid). Where `schema` contains the current schema being rendered. Only schemas from [Components object](https://www.asyncapi.com/docs/specifications/2.0.0/#a-name-componentsobject-a-components-object) are used. - - `$$everySchema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-js/blob/master/API.md#Schema) and [`schemaName`](https://github.com/asyncapi/parser-js/blob/master/API.md#Schema+uid). Where `schema` contains the current schema being rendered. Every [Schema object](https://www.asyncapi.com/docs/specifications/2.0.0/#schemaObject) from the entire AsyncAPI file is used. - - `$$objectSchema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-js/blob/master/API.md#Schema) and [`schemaName`](https://github.com/asyncapi/parser-js/blob/master/API.md#Schema+uid). Where `schema` contains the current schema being rendered. All the [Schema objects](https://www.asyncapi.com/docs/specifications/2.0.0/#schemaObject) with type object is used. - - `$$parameter$$`, within the template-file you have access to two variables [`parameter`](https://github.com/asyncapi/parser-js/blob/master/API.md#ChannelParameter) and [`parameterName`](https://github.com/asyncapi/parser-js/blob/master/API.md#Channel+parameters). Where the `parameter` contains the current parameter being rendered. - - `$$securityScheme$$`, within the template-file you have access to two variables [`securityScheme`](https://github.com/asyncapi/parser-js/blob/master/API.md#SecurityScheme) and [`securitySchemeName`](https://github.com/asyncapi/parser-js/blob/master/API.md#Components+securitySchemes). Where `securityScheme` contains the current security scheme being rendered. + - `$$channel$$`, within the template-file you have access to two variables [`channel`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channel) and [`channelName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channels). Where the `channel` contains the current channel being rendered. + - `$$message$$`, within the template-file you have access to two variables [`message`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message) and [`messageName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#message). Where `message` contains the current message being rendered. + - `$$schema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema). Where `schema` contains the current schema being rendered. Only schemas from [Components object](https://www.asyncapi.com/docs/reference/specification/latest#componentsObject) are used. + - `$$everySchema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schemas). Where `schema` contains the current schema being rendered. Every [Schema object](https://www.asyncapi.com/docs/specifications/2.0.0/#schemaObject) from the entire AsyncAPI file is used. + - `$$objectSchema$$`, within the template-file you have access to two variables [`schema`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schema) and [`schemaName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#schemas). Where `schema` contains the current schema being rendered. All the [Schema objects](https://www.asyncapi.com/docs/reference/specification/latest#multiFormatSchemaObject) with type object is used. + - `$$parameter$$`, within the template-file you have access to two variables [`parameter`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channelparameter) and [`parameterName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channelparameters). Where the `parameter` contains the current parameter being rendered. + - `$$securityScheme$$`, within the template-file you have access to two variables [`securityScheme`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#securityscheme) and [`securitySchemeName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#securityschemes). Where `securityScheme` contains the current security scheme being rendered. The file name will be equal to `*Name` variable. diff --git a/pages/docs/tools/generator/hooks.md b/pages/docs/tools/generator/hooks.md index d2c06ddc0c4..bc00f8e13cc 100644 --- a/pages/docs/tools/generator/hooks.md +++ b/pages/docs/tools/generator/hooks.md @@ -10,7 +10,7 @@ The following types of hooks are currently supported: |---|---|---|---| | `generate:before` | Called after registration of all filters and before the generator starts processing of the template. | void : Nothing is expected to be returned. | [The generator instance](https://github.com/asyncapi/generator/blob/master/docs/api.md) | `generate:after` | Called at the very end of the generation. | void : Nothing is expected to be returned. | [The generator instance](https://github.com/asyncapi/generator/blob/master/docs/api.md) -| `setFileTemplateName ` | Called right before saving a new file generated by [file template](./file-templates.md). | string : a new filename for the generator to use for the file template. | [The generator instance](https://github.com/asyncapi/generator/blob/master/docs/api.md) and object in the form of `{ "originalFilename" : string }` +| `setFileTemplateName ` | Called right before saving a new file generated by [file template](./file-templates). | string : a new filename for the generator to use for the file template. | [The generator instance](https://github.com/asyncapi/generator/blob/master/docs/api.md) and object in the form of `{ "originalFilename" : string }` The generator parses: - All the files in the `.hooks` directory inside the template. diff --git a/pages/docs/tools/generator/index.md b/pages/docs/tools/generator/index.md index 544528af34e..c8d2ca26004 100644 --- a/pages/docs/tools/generator/index.md +++ b/pages/docs/tools/generator/index.md @@ -19,7 +19,7 @@ The AsyncAPI generator is a tool that generates anything you want using the **[A 1. The **Generator** receives the **[Template](generator/template)** and **[AsyncAPI Document](generator/asyncapi-document)** as inputs. 2. The **Generator** sends to the **[Parser](generator/parser)** the **asyncapiString** which is a stringified version of the original **AsyncAPI Document**. 3. The **Parser** uses additional plugins such as the OpenAPI, RAML, or Avro schemas to validate custom schemas of message payloads defined in the **AsyncAPI Document**. -4. If the **Parser** determines that the original **AsyncAPI Document** is valid, it manipulates the document and returns a set of helper functions and properties and bundles them together into an **asyncapi** variable that is an instance of [**AsyncAPIDocument**](https://github.com/asyncapi/parser-js/blob/master/API.md#module_@asyncapi/parser+AsyncAPIDocument). The **asyncapi** helper functions make it easier to access the contents of the AsyncAPI Document. +4. If the **Parser** determines that the original **AsyncAPI Document** is valid, it manipulates the document and returns a set of helper functions and properties and bundles them together into an **asyncapi** variable that is an instance of [**AsyncAPIDocument**](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#asyncapidocument). The **asyncapi** helper functions make it easier to access the contents of the AsyncAPI Document. 5. At this point, the **Generator** passes the **[asyncapi](generator/asyncapi-document#method-2-asyncapi-and-template)**, the **[originalAsyncAPI](generator/asyncapi-document#method-1-originalasyncapi-and-template)**, and the **params** which collectively make up the **[Template Context](generator/asyncapi-context)** to the **Render Engine**. 6. AsyncAPI has two **Render Engines**([react](generator/react-render-engine) and [nunjucks](generator/nunjucks-render-engine). Depending on which one you've specified in your `package.json`, the **Generator** knows the right **Render Engine** to pass both the **Template Files** and the **Template Context**. 7. Once the **Render Engine** receives the **Template Files** and the **Template Context**, it injects all the dynamic values in your react or nunjucks based **Template Files** using the **Template Context**. As a result, the **Render Engine** generates **markdown**, **pdf**, **boilerplate code**, and **anything else** you specified to be generated as output. diff --git a/pages/docs/tools/generator/nunjucks-render-engine.md b/pages/docs/tools/generator/nunjucks-render-engine.md index 727cd212188..a64b64ab896 100644 --- a/pages/docs/tools/generator/nunjucks-render-engine.md +++ b/pages/docs/tools/generator/nunjucks-render-engine.md @@ -11,7 +11,7 @@ weight: 120 1. Templates may contain `partials` (reusable chunks). They must be stored in the `.partials` directory under the template directory. [Read more about partials](#partials). 1. Templates may contain multiple files. Unless stated otherwise, all files will be rendered. 1. The default variables you have access to in any the template file are the following: - - `asyncapi` that is a parsed spec file object. Read the [API](https://github.com/asyncapi/parser-js/blob/master/API.md#AsyncAPIDocument) of the Parser to understand what structure you have access to in this parameter. + - `asyncapi` that is a parsed spec file object. Read the [API](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#asyncapidocument) of the Parser to understand what structure you have access to in this parameter. - `originalAsyncAPI` that is an original spec file before it is parsed. - `params` that contain the parameters provided when generating. diff --git a/pages/docs/tools/generator/parser.md b/pages/docs/tools/generator/parser.md index 1e9a060fde5..399308d679e 100644 --- a/pages/docs/tools/generator/parser.md +++ b/pages/docs/tools/generator/parser.md @@ -68,7 +68,7 @@ const channelNames = asyncAPIDocument.channelNames(); const messages = asyncAPIDocument.allMessages(); ``` -> The Parser gives you access to a number of these [helper functions](https://github.com/asyncapi/parser-js/blob/master/API.md) that you can implement to access the contents of your AsyncAPI document. +> The Parser gives you access to a number of these [helper functions](https://github.com/asyncapi/parser-api/blob/master/docs/api.md) that you can implement to access the contents of your AsyncAPI document. ## AsyncAPI document validation process diff --git a/pages/docs/tools/generator/react-render-engine.md b/pages/docs/tools/generator/react-render-engine.md index e92cb236511..1cf74b983e1 100644 --- a/pages/docs/tools/generator/react-render-engine.md +++ b/pages/docs/tools/generator/react-render-engine.md @@ -42,7 +42,7 @@ For further information about components, props, etc, see the [Generator React S - The file is not in the list of `nonRenderableFiles` in the template configuration 1. New lines are automatically added after each `Text` component. 1. The props you have access to in the rendering function are: - - `asyncapi` which is a parsed spec file object. Read the [API](https://github.com/asyncapi/parser-js/blob/master/API.md#AsyncAPIDocument) of the Parser to understand what structure you have access to in this parameter. + - `asyncapi` which is a parsed spec file object. Read the [API](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#asyncapidocument) of the Parser to understand what structure you have access to in this parameter. - `originalAsyncAPI` which is an original spec file before it is parsed. - `params` that contain the parameters provided when generating. 1. All the file templates are supported where the variables are provided after the default props as listed above. diff --git a/pages/docs/tools/glee/_section.md b/pages/docs/tools/glee/_section.md new file mode 100644 index 00000000000..12696528246 --- /dev/null +++ b/pages/docs/tools/glee/_section.md @@ -0,0 +1,4 @@ +--- +title: Glee +weight: 10 +--- \ No newline at end of file diff --git a/pages/docs/tools/glee/authentication.md b/pages/docs/tools/glee/authentication.md new file mode 100644 index 00000000000..2cd7a0101c7 --- /dev/null +++ b/pages/docs/tools/glee/authentication.md @@ -0,0 +1,188 @@ +--- +title: 'Authentication functions' +weight: 3 +--- + +# Getting started with Authentication functions + +Authentication in Glee can be done using authentication functions. Authentication functions are files that export either one or both of the `clientAuth` and `serverAuth` Node.js functions: + +```js +/* websocket.js */ + +export async function serverAuth({ authProps, done }) { + //server auth logic +} + +export async function clientAuth({ parsedAsyncAPI, serverName }) { + //client auth logic +} +``` + +Glee looks for authentication files in the `auth` directory by default but it can be configured using [glee config file](../config-file.md). +The name of the authentication file should be the name of the targeted server that the authentication logic should work for. + +## Supported Authentication Values in asyncapi.yaml file + +AsyncAPI currently supports a variety of authentication formats as specified in the [documentation](https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.15#securitySchemeObject), however Glee supports the following authentication schemas. + +- userPassword +- http ("bearer") +- httpApiKey +- Oauth2 + +A sample `asyncapi.yaml` for a server with security requirements and a `userPassword` security schemes is shown below: + +```yaml +##server asyncAPI schema +asyncapi: 3.0.0 +info: + title: AsyncAPI IMDB server + version: 1.0.0 + description: This app is a dummy server that would stream the trending/upcoming anime. +servers: + trendingAnimeServer: + host: 'localhost:8081' + protocol: http + security: + - $ref: '#/components/securitySchemes/userPass' + + ... + +components: + securitySchemes: + userPass: + type: userPassword + +``` + +A sample `asyncapi.yaml` for a client that implements some of the requirements of the server above: + +```yaml +##client asyncAPI schema +servers: + trendingAnime: + host: localhost:8081 + protocol: http + security: + - $ref: '#/components/securitySchemes/userPass' + testwebhook: + host: localhost:9000 + protocol: ws +x-remoteServers: + - trendingAnime + + ... + +components: + securitySchemes: + userPass: + type: userPassword + +``` + +**The Client asyncapi.yaml file does not need to implement all the security requirements in the server, it only needs to implement the ones that it uses like *userPassword* here.** + + +Glee can act as both a server and a client. Hence the need for `serverAuth` and `clientAuth`. Glee acts as a client when the server name is included in the `x-remoteServers` property in the `asyncapi.yaml` file. + +When Glee acts as a client, it can connect to a Glee server, and when Glee acts as a server it accepts connections from other Glee clients. Hence a Glee application can both accept connections from clients while also sending requests to other Glee applications (servers) at the same time. + +When a security requirement is specified in the `asyncapi.yaml` file and Glee acts as a server, the `serverAuth` function should be implemented, if Glee acts as a client then the `clientAuth` function should be implemented. If Glee is being used as both client and server, then it should have both the `clientAuth` and `serverAuth` functions. + +## Server Authentication in Glee + +The `serverAuth` function takes an argument that can be destructured as follows + +| Attribute | Description | +| ---------- | --------------------------------------------------------------- | +| done | The done function that tells the server to proceed. | +| authProps | The authentication parameters recieved from the client. | +| serverName | The name of the server/broker from which the event was emitted. | +| doc | The parsedAsyncAPI schema | + +### done() + +The `done` parameter in the `serverAuth` function allows the broker/server to know what to do next depending on the boolean value you pass to it. + +```js +/* websocket.js */ + +export async function serverAuth({ authProps, done }) { + if (isValidUser(authProps)) { + done(true); + } else { + done(false, 401, "Unauthorized"); + } +} +``` +**Parameters for done():** + +- Authentication Result (Boolean): true for success, false for failure. +- HTTP Status Code (Integer): Code for authentication failure (e.g., 401 for Unauthorized). +- Status Message (String): Description of the authentication result (e.g., "Unauthorized"). + +When `true` is passed to the done parameter, the server/broker knows to go ahead and allow the client to connect, which means authentication has succeeded. However if the `done` parameter is called with `false` then the server knows to throw an error message and reject the client, which means authenticatio has failed. + +`done()` should always be the last thing called in a `serverAuth` function, Glee won't execute any logic beyond the `done()` call. + +### authProps + +`authProps` implements a couple of methods that allows the server to retrieve the authentication parameters from the client, below are the current available methods; + +```js +export async function serverAuth({ authProps, done }) { + //some network request + + authProps.getOauthToken() + authProps.getHttpAPIKeys('api_key') + authProps.getToken() + authProps.getUserPass() + + // done(false, 401, "Unauthorized"); + done(false) +} +``` + +| Method | Description | +| ---------------------- | ------------------------------------------------------------------------------------------------ | +| `getOauthToken()` | returns the oauth authentication parameter | +| `getHttpAPIKeys(name)` | returns the HttpAPIKeys parameter with the specified name from either headers or query parameter | +| `getToken()` | returns the http bearer token parameter | +| `getUserPass()` | returns username and password parameters | + +## Client Authentication in Glee + +The `clientAuth` function also takes an argument, and it's argument can be destructured as follows + +| Attribute | Description | +| -------------- | ------------------------------------------------------------------------------------- | +| parsedAsyncAPI | The parsedAsyncAPI schema. | +| serverName | The name of the server/broker from with the authentication parameters are being sent. | + +### possible authentication parameters + +The possible authentication parameters are shown in the code snippet below: + +```js +export async function clientAuth({ serverName }) { + return { + token: process.env.TOKEN, + oauth: process.env.OAUTH2, + apiKey: process.env.APIKEY, + userPass: { + user: process.env.user, + password: process.env.password, + }, + } +} +``` + +**The name of the authentication parameters should be the same as the names specified in the asyncAPI.yaml file.** + +| auth type | values | +| ------------------------------------- | ---------------------------------------------------------------------- | +| http bearer (JWT) | Value should be a JWT string | +| Oauth2 | The value should should be a string | +| httpApiKey in headers or query params | The value should be a string | +| userPass | The value should be an object with the user and password as properties | diff --git a/pages/docs/tools/glee/bearerToken.md b/pages/docs/tools/glee/bearerToken.md new file mode 100644 index 00000000000..9f1d2244ba2 --- /dev/null +++ b/pages/docs/tools/glee/bearerToken.md @@ -0,0 +1,109 @@ +--- +title: 'Http (Bearer Token)' +weight: 5 +--- + +## Getting started with Bearer Token authentication + +Bearer Token authentication is one of the most popular forms of authentication and is widely used because of its percieved security. This guide will walk through how to implement bearer token authentication in Glee. + +A sample `asyncapi.yaml` for a server with security requirements and user password security scheme is shown below: + +```yaml +##server asyncAPI schema +asyncapi: 3.0.0 +info: + title: AsyncAPI IMDB server + version: 1.0.0 + description: This app is a dummy server that would stream the trending/upcoming anime. +servers: + trendingAnimeServer: + host: 'localhost:8081' + protocol: http + security: + - $ref: '#/components/securitySchemes/token' + + ... + +components: + securitySchemes: + token: + type: http + scheme: bearer + bearerFormat: JWT + +``` + +A sample `asyncapi.yaml` for a client that implements some of the requirements of the server above: + +```yaml +##client asyncAPI schema +servers: + trendingAnime: + host: localhost:8081 + protocol: http + security: + - $ref: '#/components/securitySchemes/token' + testwebhook: + host: localhost:9000 + protocol: ws +x-remoteServers: + - trendingAnime + + ... + +components: + securitySchemes: + token: + type: http + scheme: bearer + bearerFormat: JWT + +``` + +**The Client asyncapi.yaml file does't need to implement all the security requirements in the server, it only needs to implement the ones that it uses like &*http (bearer token)* here.** + +### Client Side + +Following the client `asyncapi.yaml` file above, create a file named `trendingAnime.ts` in the `auth` directory, since that is the server that has the security Property. + +```bash +touch auth/trendingAnime.ts +``` + +When using the `bearer` security scheme, it is important that you pass the parameters as follows: + +```js +export async clientAuth({ parsedAsyncAPI, serverName }) { + return { + token: process.env.TOKEN + } +} +``` + +Glee will utilize the `token` for server authentication, employing it in the header with the format: Authorization: Bearer {token}. + +### Server side + +From the server `asyncapi.yaml` file above, create a file named `trendingAnimeServer.ts` in the `auth` directory, since that is the server that has the security Property. + +```bash +touch auth/trendingAnimeServer.ts +``` + +On the server side, you can retrieve the values as follows + +```js + +export async serverAuth({ authProps, done }) { + authProps.getToken() + // your authentication logic here... + done(true|false) +} + +``` + +`getToken()` return a string which contains the token that was sent from the client. + + + diff --git a/pages/docs/tools/glee/glee-template.md b/pages/docs/tools/glee/glee-template.md new file mode 100644 index 00000000000..346a28bacb3 --- /dev/null +++ b/pages/docs/tools/glee/glee-template.md @@ -0,0 +1,104 @@ +--- +title: "Create AsyncAPI Glee template" +weight: 170 +--- +This tutorial teaches you how to create a simple glee template. You'll use the AsyncAPI Glee template you develop to generate Javascript code. Additionally, you'll create a template code with a reusable component to reuse the custom functionality you create and test your code using an WS server. + + +{`asyncapi: 3.0.0 +info: + title: 'Hello, Glee!' + version: 1.0.0 +servers: + websockets: + host: 0.0.0.0:3000 + protocol: ws +channels: + hello: + address: hello + messages: + hello: + $ref: '#/components/messages/hello' +operations: + onHello: + action: receive + channel: + $ref: '#/channels/hello' + reply: + channel: + $ref: "#/channels/hello" + SendHello: + action: send + channel: + $ref: "#/channels/hello" +components: + messages: + hello: + payload: + type: string`} + + +Let's break it down into pieces: + + +{`info: + title: 'Hello, Glee!' + version: 1.0.0`} + + +The `info` section provides general information about the API, including its title and version. + +Moving on, let's talk about the `servers` section. + + +{`servers: + websockets: + host: 0.0.0.0:3000 + protocol: ws`} + + +The servers section defines the different servers where the API can be accessed. In this case, there is a single server named "websockets" that uses the WebSocket protocol (`ws`) and listens on the address `ws://0.0.0.0:3000`. + +Now lets move on to the `channels` section. This section is used to describe the event names your API will be publishing and/or subscribing to. + + +{`channels: + hello: + address: hello + messages: + hello: + $ref: '#/components/messages/hello' +operations: + onHello: + action: receive + channel: + $ref: '#/channels/hello' + reply: + channel: + $ref: "#/channels/hello" + sendHello: + action: send + channel: + $ref: '#/channels/hello'`} + + +The channels section defines the communication channels available in the API. In this case, there's a channel named "hello". This channel supports both sending and receiving. + +The `receive` action indicates that messages received on the `hello` channel should follow the structure defined in the hello message component. Under this action, `reply` which is in a request-reply operation, contains the payload on `onHello.js` function. +The `send` action specifies that the operation with ID `sendHello` is used for sending messages to the `hello` channel. The message structure is referenced from the hello message component. + +Next is the `payload` property under `hello` message component which is used to understand how the event should look like when publishing to that channel: + + +{`components: + messages: + hello: + payload: + type: string`} + + +The components section contains reusable elements, in this case, a definition for the "hello" message. It specifies that the payload of the "hello" message should be of type string. + +## Summary + +In this tutorial, you learned how to create an AsyncAPI specification document via a simple example with a glee template. diff --git a/pages/docs/tools/glee/httpApiKey.md b/pages/docs/tools/glee/httpApiKey.md new file mode 100644 index 00000000000..e95131edbaa --- /dev/null +++ b/pages/docs/tools/glee/httpApiKey.md @@ -0,0 +1,111 @@ +--- +title: 'httpAPIKey' +weight: 5 +--- + +## Getting started with httpAPIKey authentication + +This guide will walk through how to implement authentication using the `httpAPiKey` security scheme in Glee. + +A sample `asyncapi.yaml` for a server with security requirements and user `HttpApiKey` security scheme is shown below: + +```yaml +##server asyncAPI schema +asyncapi: 3.0.0 +info: + title: AsyncAPI IMDB server + version: 1.0.0 + description: This app is a dummy server that would stream the trending/upcoming anime. +servers: + trendingAnimeServer: + host: 'localhost:8081' + protocol: http + security: + - $ref: '#/components/securitySchemes/apiKey' + + ... + +components: + securitySchemes: + apiKey: + type: httpApiKey + name: api_key + in: query + +``` + +A sample `asyncapi.yaml` for a client that implements some of the requirements of the server above: + +```yaml +##client asyncAPI schema +servers: + trendingAnime: + host: localhost:8081 + protocol: http + security: + - $ref: '#/components/securitySchemes/apiKey' + testwebhook: + host: localhost:9000 + protocol: ws +x-remoteServers: + - trendingAnime + + ... + +components: + securitySchemes: + apiKey: + type: httpApiKey + name: api_key + in: query + + +``` + +The `httpApiKey` could be in either the header or query parameter. + +**The Client asyncapi.yaml file does not need to implement all the security requirements in the server, it only needs to implement the ones that it uses like *httpApiKey* here.** + +### Client Side + +Following the client `asyncapi.yaml` file above, create a file named `trendingAnime.ts` in the `auth` directory, since that is the server that has the security Property. + +```bash +touch auth/trendingAnime.ts +``` + +When using the `HttpApiKey` security scheme, it is important that you pass the parameters as follows: + +```js +export async clientAuth({ parsedAsyncAPI, serverName }) { + return { + apiKey: process.env.APIKEY + } +} +``` + +`apiKey` should be the name of the security requirement as specified in your `asyncapi.yaml` file, and it's value should be a string. + + +### Server side + +From the server `asyncapi.yaml` file above, create a file named `trendingAnimeServer.ts` in the `auth` directory, since that is the server that has the security Property. + +```bash +touch auth/trendingAnimeServer.ts +``` + +On the server side, you can retrieve the values as follows + +```js + +export async serverAuth({ authProps, done }) { + authProps.getHttpAPIKeys('api_key')() + + done(true) +} + +``` + +`getHttpAPIKeys(name)` takes a name parameter to specify the name of the httpApiKey that is desired. Then it returns an object containing the httpApiKey value that was sent from the client. + diff --git a/pages/docs/tools/glee/index.md b/pages/docs/tools/glee/index.md new file mode 100644 index 00000000000..aca98544169 --- /dev/null +++ b/pages/docs/tools/glee/index.md @@ -0,0 +1,159 @@ +--- +title: Getting Started +weight: 80 +--- + +## Introduction + +[Glee](https://github.com/asyncapi/glee) is a spec-first framework that helps you build server-side applications. That means it operates on the principle of defining the API specification (AsyncAPI) before diving into the actual implementation of the application logic. It leverages that principle to make you more productive: + +- Glee ensures your code and AsyncAPI definition are on par, eliminating the problem of outdated documentation. By having both the code and the AsyncAPI definition in sync, you can ensure that the API documentation is always up to date, accurate, and reflects the current state of the application. Glee takes care of this automatically for you. +- Glee lets you focus on what matters and handles the rest for you. You only write the code for your business use-case. Glee takes care of performance, scalability, resilience, and everything you need to make your application production-ready. +- Glee validates the schema of the payload that it receives, if it doesn't conform to the schema that is defined in the AsyncAPI document, it throw an error telling user that the server received an invalid payload. + +Now, before you get started with a glee project, let's take a high level view of Application structure what glee resonates with. + +## Application structure + +Glee expects your project to have some files and folders with special names. When you run `asyncapi new glee`, [AsyncAPI CLI](https://github.com/asyncapi/cli) generates a boilerplate application structure by creating a new folder and populating an initial set of files as shown below. You can continue working in this default structure, adding new components, as described throughout the documentation of asyncapi cli. + +``` +├─ functions (required) +│ ├─ onHello.js +│ └─ ... +├─ lifecycle (optional) +│ ├─ onConnect.js +│ └─ ... +├─ .env (optional) +├─ asyncapi.(yaml | yml | json) (required) +├─ glee.config.js (optional) +├─ package.json (required) +``` + +|File/Directory|Description| +|---|---| +|functions|**Required.** This directory contains all the functions that Glee must execute when it receives a message from the server. Each file must export a default async function. +|lifecycle|This directory contains application lifecycle functions. These functions will be executed when certain events happen in the application. E.g., `onConnect`, `onServerReady`, `onDisconnect`, etc. +|.env|The environment variables of your application. **DO NOT PUT SECRETS HERE**. +|asyncapi.(yaml or json or yml)|**Required.** The [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest) file defines your API. Make sure all the `publish` operations have an assigned `operationId` that matches a file name (excluding the extension) in the `functions` directory. +|glee.config.js| The Glee configuration file. +|package.json|**Required.** The Node.js package definition file. Make sure you include `@asyncapi/glee` as a dependency and add two scripts: `dev` and `start`. They should be running `glee dev` and `glee start` respectively. + +To understand the structure in a broader way, please refer to the associated page's links. + +### Let's create a glee project to simplify the app structure + +We will consider a simple WebSocket API using glee to understand its magic. We will create a simple WebSocket server that receives a current time from the client and then send a "good morning", "good evening" or "good night" respectively. + +To setup a project, you should follow our installation page on how to setup glee on your environment. + +We recommend creating a new Glee app using our official CLI which sets up everything automatically. (You don't need to create an empty directory. create-glee-app will make one for you.) To create a project, run: `asyncapi new glee` + +Once the process is completed, you should have a new Glee app ready for development and see these files that were made. + +![glee_structure](glee_struct.png) + +#### Define our Spec for our API + +Glee being a spec-first framework, development starts with defining your API spec. To know more details into it, you can follow glee template to understand it step by step. For our case we will define our API: + +```yaml +asyncapi: 3.0.0 +info: + title: Greet Bot + version: 1.0.0 +servers: + websockets: + host: 0.0.0.0:3000 + protocol: ws +channels: + greet: + address: greet + messages: + greet: + $ref: '#/components/messages/greet' + time: + $ref: '#/components/messages/time' + time: + address: time + messages: + time: + $ref: '#/components/messages/time' +operations: + onGreet: + action: receive + channel: + $ref: '#/channels/greet' + reply: + channel: + $ref: '#/channels/greet' + sendGreet: + action: send + channel: + $ref: '#/channels/time' +components: + messages: + time: + payload: + type: object + properties: + currentTime: + type: number + name: + type: string + greet: + payload: + type: string + +``` + +This will be the Specification that defines our API, in our case, it is very simple, as we will be sending a name and the time of the day, and our API will greet us accordingly. + +One thing to note here is the `operations` item, this is needed and is a crucial part of glee, as this is how we will be connecting our business logic with our spec, `onGreet` is the name of the function that will be called every time a certain operation occurs. In our case whenever `/greet` channel receives a message, `onGreet` function is called. + +#### Define our operation function + +Now for our case, we will be adding a file `functions/onGreet.js` and writing up the logic for parsing our time and sending a response. + +```javascript +export default async function (event) { + const { name, time } = event.payload + const t = new Date(time) + const curHr = t.getHours() + let response = '' + if (curHr < 12) { + response = `Good Morning ${name}` + } else if (curHr < 18) { + response = `Good Afternoon ${name}` + } else { + response = `Good Evening ${name}` + } + return { + reply: [ + { + payload: response, + }, + ], + } +} + +``` + +Every file in the functions folder acts as a handler to develop business logic for glee, every file should export an async function that receives an event parameter, where you have access to payload and server details. + +#### Running and testing your application + +We will not execute the application and carry out testing with Postman to ensure that it is functioning as intended. + +Now to execute your glee application, just run: + +``` +npm run dev +# or +npm run start +``` +To send a WebSocket request with a payload e.g. `{"name":"john", "time": "1567906535"}` to `ws://localhost:3000/greet`, open Postman and checkout the endpoint: + +![glee_response](glee_resp.png) + +So, this is how easy it is to build a WebSocket API using Glee. You can also check out the example code [here](https://github.com/Souvikns/greet-bot). diff --git a/pages/docs/tools/glee/installation.md b/pages/docs/tools/glee/installation.md new file mode 100644 index 00000000000..3b13855e248 --- /dev/null +++ b/pages/docs/tools/glee/installation.md @@ -0,0 +1,134 @@ +--- +title: 'Installation guide' +weight: 30 +--- + +## Glee Installation + +Before installing Glee into your project, make sure you have pre-installed NPM, NodeJs and [AsyncAPI CLI](https://github.com/asyncapi/cli) tools on your system. + +### Automatic Installation + +The best way to get started with Glee is by using AsyncAPI CLI, which sets up everything automatically for you. +To create a project, run: + +```sh +asyncapi new glee +``` + +> For more information on how to install the AsynAPI CLI, you can review the [CLI installation guide](https://www.asyncapi.com/docs/tools/cli/installation). + +On installation, you'll find next steps after your project created: + +``` +Your project "project" has been created successfully! + +Next steps: + + cd project + npm install + npm run dev + +Also, you can already open the project in your favorite editor and start tweaking it +``` + +While making twists to your application, you can follow along with our getting started guide on the relevant page. + +### Manual Installation + +To manually create a new app, create a new folder e.g. `myapp` so the folder structure would look like below; + +``` +├─ functions (required) +│ ├─ onHello.js +│ └─ ... +├─ lifecycle (optional) +│ ├─ onConnect.js +│ └─ ... +├─ .env (optional) +├─ asyncapi.(yaml | yml | json) (required) +├─ glee.config.js (optional) +├─ package.json (required) +``` + +Install the required packages inside a new folder: + +```js +npm init -y +npm install @asyncapi/glee +``` + +Open your package.json file and add the following scripts: + +```js +{ + "scripts": { + "docs": "glee docs", + "dev": "glee dev", + "start": "glee start", + } +} +``` + +These scripts refer to the different stages of developing an application. + +- `glee docs`: This script generates documentation for your project using the "Glee" documentation tool. This documentation includes information about your project's APIs, modules, and usage instructions. + +- `glee dev`: This script is used for starting a development server. It launches a local development server, build your project in development mode, or perform other development-related tasks. + +- `glee start`: This script is responsible for starting your project or application. It is used to launch a production-ready server or application instance. + +#### Creating `asyncapi.yaml` file and other required directories + +Create a yaml file that supports capable of receiving a "hello {name}" message with the protocol as `ws` and the channel name as `hello` the hello API will subscribe to. The operationId property is `onHello` that's the name of function and the payload property is type string publishing to that channel. + +```yaml +asyncapi: 3.0.0 +info: + title: 'Hello, Glee!' + version: 1.0.0 +servers: + websockets: + host: 0.0.0.0:3000 + protocol: ws +channels: + hello: + address: hello + messages: + hello: + $ref: '#/components/messages/hello' +operations: + onHello: + action: receive + channel: + $ref: '#/channels/hello' + reply: + channel: + $ref: "#/channels/hello" + SendHello: + action: send + channel: + $ref: "#/channels/hello" +components: + messages: + hello: + payload: + type: string +``` + +Create an operation function `onHello.js` inside `myapp/functions`: + +```js +export default async function (event) { + return { + reply: [{ + payload: `Hello from Glee! You said: "${event.payload}".` + }] + } +} +``` + +#### Run the Development Server + +- Run `npm run dev` to start the development server. +- Connect to `ws://localhost:3000/hello` and send a WebSocket request with a payload e.g. {"john"} diff --git a/pages/docs/tools/glee/intro-auth.md b/pages/docs/tools/glee/intro-auth.md new file mode 100644 index 00000000000..c657fef8ecd --- /dev/null +++ b/pages/docs/tools/glee/intro-auth.md @@ -0,0 +1,21 @@ +--- +title: 'Introduction to Glee Authentication' +weight: 30 +--- + +Glee comes with Authentication features which help you erifying the identity of users or entities attempting to access a system or application. It ensures that only authorised individuals or systems are granted access, protecting against unauthorised intrusions and data breaches. Glee simplifies this vital process by offering multiple authentication methods, each tailored to different use cases: + +# Authentication Using Authentication Functions: +Glee allows you to implement custom authentication logic by utilising authentication functions. This flexible approach enables developers to craft tailored authentication mechanisms, ensuring that access to resources is controlled precisely as required. + + +# HTTP Bearer Token Authentication: +In today's API-driven world, bearer token authentication is a widely adopted method. Glee supports this approach, allowing clients to present a token as proof of their identity, thus ensuring secure and efficient access to resources. + +# HttpApiKey Authentication: +Glee's authentication suite includes support for API key authentication, which is vital for protecting web APIs. By using API keys, you can regulate access to your services, making it an essential component of your application's security strategy. + +# Username and Password Authentication: +Traditional yet still crucial, username and password authentication remains a reliable option within Glee's toolkit. This method allows users to access systems or applications by providing their unique credentials, ensuring a familiar and straightforward login experience. + +Glee's authentication features not only provide layers of security but also offer the flexibility needed to meet your unique requirements. Whether you're developing a web application, a mobile app, or any other application, Glee's authentication methods empower you to tailor your security measures to suit the demands of your project. With Glee, you can build and maintain a secure digital environment, ensuring that only authorised users and systems gain access, protecting your valuable data and resources. \ No newline at end of file diff --git a/pages/docs/tools/glee/userPassword.md b/pages/docs/tools/glee/userPassword.md new file mode 100644 index 00000000000..fc761310ed1 --- /dev/null +++ b/pages/docs/tools/glee/userPassword.md @@ -0,0 +1,106 @@ +--- +title: 'userPassword' +weight: 5 +--- + +## Getting started with username and password authentication + +User and password authentication is one of the most basic forms of authentication. This guide will walk through how to implement username and password authentication in Glee. + +A sample `asyncapi.yaml` for a server with security requirements and user password security scheme is shown below: + +```yaml +##server asyncAPI schema +asyncapi: 3.0.0 +info: + title: AsyncAPI IMDB server + version: 1.0.0 + description: This app is a dummy server that would stream the trending/upcoming anime. +servers: + trendingAnimeServer: + host: 'localhost:8081' + protocol: http + security: + - $ref: '#/components/securitySchemes/userPass + + ... + +components: + securitySchemes: + userPass: + type: userPassword + +``` + +A sample `asyncapi.yaml` for a client that implements some of the requirements of the server above: + +```yaml +##client asyncAPI schema +servers: + trendingAnime: + host: localhost:8081 + protocol: http + security: + - $ref: '#/components/securitySchemes/userPass + testwebhook: + host: localhost:9000 + protocol: ws +x-remoteServers: + - trendingAnime + + ... + +components: + securitySchemes: + userPass: + type: userPassword + +``` + +**The Client asyncapi.yaml file does not need to implement all the security requirements in the server, it only needs to implement the ones that it uses like &*userPassword* here.** + +### Client Side + +Following the client `asyncapi.yaml` file above, create a file named `trendingAnime.ts` in the `auth` directory, since that is the server that has the security Property. + +```bash +touch auth/trendingAnime.ts +``` + +When using the `userPassword` security scheme, it is important that you pass the parameters as follows: + +```js +export async clientAuth({ parsedAsyncAPI, serverName }) { + return { + userPass: { + user: process.env.user, + password: process.env.password, + }, + } +} +``` + +`userPass` should be the name of the security requirement as specified in your `asyncapi.yaml` file, then pass `user` and `password` as it's properties + + +### Server side + +From the server `asyncapi.yaml` file above, create a file named `trendingAnimeServer.ts` in the `auth` directory, since that is the server that has the security Property. + +```bash +touch auth/trendingAnimeServer.ts +``` + +On the server side, you can retrieve the values as follows + +```js + +export async serverAuth({ authProps, done }) { + authProps.getUserPass() + + done(true) +} + +``` + +`getUserPass()` return an object containing the username and password that was sent from the client. diff --git a/pages/docs/tutorials/create-asyncapi-document.md b/pages/docs/tutorials/create-asyncapi-document.md index 946bb016aed..f6addf842c8 100644 --- a/pages/docs/tutorials/create-asyncapi-document.md +++ b/pages/docs/tutorials/create-asyncapi-document.md @@ -8,26 +8,24 @@ weight: 80 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. This smart lighting system is a use case of the Internet of Things (IoT). You will create a Smarty Lighting Streetlights API using Node.js and Mosquitto (MQTT) as the message broker. This API will allow you to manage city lights remotely. +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." -- Streetlights will publish information about their environmental lighting to the broker. +- The Streetlights application will receive information about environmental lighting. -- Your application will connect to the broker and receive a stream of events from all the streetlights reporting their conditions. +- The Streetlights application will connect to the broker and receive a stream of events from all the streetlights devices reporting their conditions. -- Your application decides based on events when to turn the streetlight off. - -- Your application is not aware of how many streetlights are publishing events - it just connects to the broker and receives all events. +- 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. +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. This allows interdependent services to “talk” with one another directly, even if they were written in different languages or implemented on different platforms. +[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. @@ -35,9 +33,9 @@ Furthermore, the [Pub/sub](/docs/tutorials/getting-started/event-driven-architec ## Create AsyncAPI document -In this step, you will create an AsyncAPI document to describe the Streelights API. It will help you generate the code and the documentation later on. +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.. +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. @@ -46,29 +44,28 @@ You can create a new `asyncapi.yaml` document by running: -Go ahead to create the specification documents titled `asyncapi` with a `.yaml` extension. +Create the following specification document titled `asyncapi` with a `.yaml` extension. -{`asyncapi: '2.5.0' +{`asyncapi: 3.0.0 info: - title: Streetlights API + title: Streetlights App version: '1.0.0' description: | - The Smartylighting Streetlights API allows you + 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: - url: mqtt://test.mosquitto.org + host: test.mosquitto.org protocol: mqtt channels: - light/measured: - publish: - summary: Inform about environmental lighting conditions for a particular streetlight. - operationId: onLightMeasured - message: + lightMeasured: + address: 'light/measured' + messages: + lightMeasuredMessage: name: LightMeasured payload: type: object @@ -84,51 +81,60 @@ channels: sentAt: type: string format: date-time - description: Date and time when the message was sent.`} + 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: '2.5.0' +{`asyncapi: 3.0.0 info: - title: Streetlights API + title: Streetlights App version: '1.0.0' description: | - The Smartylighting Streetlights API allows you + 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 2.5.0. +- The `asyncapi` field indicates you use the AsyncAPI version 3.0.0. -- The `info` field holds information about the Streetlights API. Here, the title, version, description and license were defined. +- 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. +Moving on, let's talk about the `servers` section: {`servers: mosquitto: - url: mqtt://test.mosquitto.org + host: test.mosquitto.org protocol: mqtt`} -In this section, you point to the Eclipse Mosquitto message broker. The `url` point to a real instance of the broker [hosted by the Mosquitto community](https://test.mosquitto.org/) and the `protocol` as 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`. But remember to change `url` to `mqtt://localhost` +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 lets move on to the `channels` section. This section is used to describe the event names your API will be publishing and/or subscribing to. +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: - light/measured: - publish: - summary: Inform about environmental lighting conditions for a particular streetlight. - operationId: onLightMeasured`} + lightMeasured: + address: 'light/measured' + messages: + lightMeasuredMessage: + name: LightMeasured + payload: + redacted for brevity`} -In this example, `light/measured` is the channel name the Streetlight API will `subscribe` to (i.e, to interact with the Streetlight API you `publish` to the broker). The `operationId` property, describes what is the name of function or method that takes care of this functionality in the generated code. +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 publishing to that channel: +Next is the `payload` property, which is used to understand how the event should look like when transfered over the specific channel: {` payload: @@ -148,15 +154,30 @@ Next is the `payload` property which is used to understand how the event should description: Date and time when the message was sent.`} -The `payload` property defines the content of the event 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 that should be a string containing a date and time. +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. -> JSON Schema Draft 07 is 100% compatible with AsyncAPI schemas. You can also use other standards to describe payload schema, like, for example [Avro](https://github.com/asyncapi/avro-schema-parser#usage). +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. -This tutorial is just a starting point; you'll need to add your own business logic to it. 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. +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, proceed to learn how to [validate your AsyncAPI document with AsyncAPI Studio](https://www.asyncapi.com/docs/tutorials/studio-document-validation). +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). diff --git a/pages/docs/tutorials/generate-code.md b/pages/docs/tutorials/generate-code.md index 0ddf35bd818..c57d46a25e9 100644 --- a/pages/docs/tutorials/generate-code.md +++ b/pages/docs/tutorials/generate-code.md @@ -6,12 +6,21 @@ weight: 100 ## Introduction -In this tutorial, you'll learn how to generate code from your AsyncAPI document using the AsyncAPI generator tool. +In this tutorial, you'll learn how to generate an application that uses the [Glee](https://github.com/asyncapi/glee) framework. You'll do it with an AsyncAPI document and the [AsyncAPI CLI](/tools/cli). ## Background context -The [AsyncAPI Generator](https://github.com/asyncapi/generator) is a tool that you can use to generate whatever you want based on the AsyncAPI document. You can generate docs and code. It can be used as a library in a Node.js application or through the [AsyncAPI CLI](https://github.com/asyncapi/cli). +[Glee](https://github.com/asyncapi/glee) is a TypeScript/JavaScript framework that enables you to create APIs and messaging clients based on your AsyncAPI document. Instead of generating code, this framework tightly integrates with your AsyncAPI document and binds functions to specific AsyncAPI operations. You only have to provide the code for these functions and Glee handles the rest. -The generator tool supports a number of templates to generate code for a variety of different languages and protocols as the output. These templates help to specify what exactly must be generated, and in this tutorial, you'll use a [Node.js template](https://github.com/asyncapi/nodejs-template). +Glee is often used with the [AsyncAPI CLI](/tools/cli) for a better development experience. + +In the previous tutorial, you created an AsyncAPI document that is used in this tutorial. + + + +If you did not follow the previous tutorial and do not have an `asyncapi.yaml` file for overview, then generate one by running the following command using the AsyncAPI CLI: +`asyncapi new --example=tutorial.yml --no-tty`. + + ## Installation guide @@ -24,42 +33,30 @@ import CliInstallation from '../../../assets/docs/fragments/cli-installation.md' -## Generate code - -To generate code from the [AsyncAPI document created in a previous tutorial](https://asyncapi.com/docs/tutorials/create-asyncapi-document), follow the steps listed below: +## Create a Glee project - - -If you did not follow the previous tutorial and do not have an `asyncapi.yaml` file ready, generate one running `asyncapi new --example=tutorial.yml --no-tty`. - - - -1. Trigger generation of the Node.js code: +1. Trigger the creation of the Glee project: - {`asyncapi generate fromTemplate asyncapi.yaml @asyncapi/nodejs-template -o output -p server=mosquitto`} + {`asyncapi new glee --name=tutorial --template tutorial`} Let's break down the previous command: - - `asyncapi generate fromTemplate` is how you use AsyncAPI Generator via the AsyncAPI CLI. - - ` asyncapi.yaml` is how you point to your AsyncAPI document and can be a URL. - - `@asyncapi/nodejs-template` is how you specify the Node.js template. - - `-o` determines where to output the result. - - `-p` defines additional parameters you want to pass to the template. Here, the `server` parameter specifies the server's name as it is defined in AsyncAPI document. + - `asyncapi new glee` is how you use Glee via the AsyncAPI CLI. + - `--name=tutorial` is how you tell the AsyncAPI CLI to name your new Glee project. + - `--template=tutorial` is how you tell the AsyncAPI CLI to use the template of a Glee project that was created specifically for this tutorial. -2. List all files in directory and check that the Node.js application is generated: +2. List all files in the directory and confirm your Glee project creation: - {`cd output && ls`} + {`cd tutorial && ls`} Upon execution of the command above, the following is an example of the expected result: {`$ ls - Dockerfile - asyncapi.yaml - docs - src + LICENSE README.md - config + asyncapi.yaml + functions package.json`} @@ -71,7 +68,7 @@ If you did not follow the previous tutorial and do not have an `asyncapi.yaml` f 2. Start the application: - {`npm start`} + {`npm run dev`} ## Send message to broker @@ -87,13 +84,14 @@ If you did not follow the previous tutorial and do not have an `asyncapi.yaml` f 3. Go back to the previous terminal to check if your application logged the streetlight condition you just sent. You should see something like this displayed in the terminal: - {`light/measured was received: - { id: 1, lumens: 3, sentAt: '2017-06-07T12:34:32.000Z' }`} + {`lightMeasured was received from mosquitto: + { id: 1, lumens: 3, sentAt: '2017-06-07T12:34:32.000Z' } + Streetlight with id "1" updated its lighting information to 3 lumens at 2017-06-07T12:34:32.000Z.`} ## Summary -In this tutorial, you learned how to generate your code from the [Streetlights API specification document created in a previous tutorial](https://asyncapi.com/docs/tutorials/create-asyncapi-document) using the AsyncAPI generator tool. +In this tutorial, you learned how to create a Glee project from the [Streetlights API specification document created in a previous tutorial](https://asyncapi.com/docs/tutorials/create-asyncapi-document). -Additionally, you've learned how to run your code by installing the generated code's dependencies and sending several test messages to the Streelights application using the MQTT client. +Additionally, you've learned how to run your code by installing the project's dependencies and sending several test messages to the Streelights application using the MQTT client. ## Next steps Now that you've completed this tutorial, go ahead and learn how to [validate your AsyncAPI messages (events)](https://asyncapi.com/docs/tutorials/message-validation) through the message validation techniques supported by AsyncAPI. diff --git a/pages/docs/tutorials/getting-started/asyncapi-documents.md b/pages/docs/tutorials/getting-started/asyncapi-documents.md index ef526918151..6d11ace3144 100644 --- a/pages/docs/tutorials/getting-started/asyncapi-documents.md +++ b/pages/docs/tutorials/getting-started/asyncapi-documents.md @@ -9,18 +9,19 @@ weight: 101 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; however, only the subset of YAML that matches the JSON capabilities is allowed. +The file format must be JSON or YAML; however, only the subset of YAML that matches the JSON capabilities is allowed. -{`asyncapi: 2.5.0 +{`asyncapi: 3.0.0 info: - title: Example - version: 0.1.0 + title: Example application + version: '0.1.0' channels: - user/signedup: - subscribe: - message: - description: An event describing that a user just signed up. + userSignup: + address: 'user/signedup' + messages: + userSignedupMessage: + description: A message describing that a user just signed up. payload: type: object additionalProperties: false @@ -32,9 +33,14 @@ channels: format: email age: type: integer - minimum: 18`} + minimum: 18 +operations: + publishUserSignedup: + action: 'send' + channel: + $ref: '#/channels/userSignup'`} -The AsyncAPI document is a machine-readable definition of your Event-Driven API. This document can be used afterward to generate documentation and code, validate the messages your application receives, and even apply API management policies to your messages before they arrive to your broker. +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. +Your API documentation is now machine-readable (easily parseable by code) so the myriad of useful applications is endless. diff --git a/pages/docs/tutorials/getting-started/coming-from-openapi.md b/pages/docs/tutorials/getting-started/coming-from-openapi.md index 78da17d7bdb..ad7f6acb2cb 100644 --- a/pages/docs/tutorials/getting-started/coming-from-openapi.md +++ b/pages/docs/tutorials/getting-started/coming-from-openapi.md @@ -1,29 +1,31 @@ --- title: "Coming from OpenAPI" -date: 2019-04-01T10:56:52+01:00 -menu: - docs: - parent: 'getting-started' 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). We wanted to have as much compatibility as possible between the two so users could reuse parts in both. +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. -You'll find lots of similarities between OpenAPI and AsyncAPI. Just bear in mind that in the world of event-driven architectures, you have more than one protocol and 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): +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' -Aside from structural differences you must know that: +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. Message payload in AsyncAPI can be any value, not just an AsyncAPI/OpenAPI schema. For instance, it could be an Avro schema. -1. [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`. +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 very similar. 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. +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. -Enough reading, it's time to get your hands dirty with some actual examples. Let's learn how to create an AsyncAPI document that defines a "Hello world" application. +Let's learn how to create an AsyncAPI document that defines a "Hello world" application. diff --git a/pages/docs/tutorials/getting-started/hello-world.md b/pages/docs/tutorials/getting-started/hello-world.md index e33a1fb2bed..654c809011f 100644 --- a/pages/docs/tutorials/getting-started/hello-world.md +++ b/pages/docs/tutorials/getting-started/hello-world.md @@ -1,109 +1,120 @@ --- title: "Hello world" -date: 2019-04-01T10:56:52+01:00 -menu: - docs: - parent: 'getting-started' weight: 30 --- -Let's define an application that's capable of receiving a "hello {name}" message. +Let's define an application that's capable of receiving a `"hello {name}"` message: -{`asyncapi: 2.6.0 +{`asyncapi: 3.0.0 info: title: Hello world application version: '0.1.0' channels: hello: - publish: - message: + address: 'hello' + messages: + sayHelloMessage: payload: type: string - pattern: '^hello .+$'`} + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} -Let's get into the details of this sample specification: +Let's get into the details of this sample AsyncAPI document: -{`asyncapi: 2.6.0 +{`asyncapi: 3.0.0 info: title: Hello world application version: '0.1.0' channels: hello: - publish: - message: + address: 'hello' + messages: + sayHelloMessage: payload: type: string - pattern: '^hello .+$'`} + 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 (2.6.0). This line doesn't have to be the first one, but it's a recommended practice. +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: 2.6.0 +{`asyncapi: 3.0.0 info: title: Hello world application version: '0.1.0' channels: hello: - publish: - message: + address: 'hello' + messages: + sayHelloMessage: payload: type: string - pattern: '^hello .+$'`} + 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: 2.6.0 + +{`asyncapi: 3.0.0 info: title: Hello world application version: '0.1.0' channels: hello: - publish: - message: + address: 'hello' + messages: + sayHelloMessage: payload: type: string - pattern: '^hello .+$'`} + 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. -In this example, you only have one channel called `hello`. The sample application subscribes to this channel to receive `hello {name}` messages. +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: 2.6.0 + +{`asyncapi: 3.0.0 info: title: Hello world application version: '0.1.0' channels: hello: - publish: - message: + address: 'hello' + messages: + sayHelloMessage: payload: type: string - pattern: '^hello .+$'`} + pattern: '^hello .+$' +operations: + receiveHello: + action: 'receive' + channel: + $ref: '#/channels/hello'`} -You can read the highlighted lines as: -> This is the `payload` of the `message` that the `Hello world application` is subscribed to. You can `publish` the `message` to the `hello` channel and the `Hello world application` will receive it. +The `operations` section is where you describe what the application is doing. Each operation has a unique identifier for example, `receiveHello`. - -{`asyncapi: 2.6.0 -info: - title: Hello world application - version: '0.1.0' -channels: - hello: - publish: - message: - payload: - type: string - pattern: '^hello .+$'`} - - -The `payload` object defines how the message must be structured. In this example, the message must be a string and match the given regular expression in the format `hello {name}` string. +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. 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. diff --git a/pages/docs/tutorials/getting-started/security.md b/pages/docs/tutorials/getting-started/security.md index 12effbf2ace..3c02ea281a7 100644 --- a/pages/docs/tutorials/getting-started/security.md +++ b/pages/docs/tutorials/getting-started/security.md @@ -1,45 +1,113 @@ --- title: "Adding security" -date: 2019-04-16T10:56:52+01:00 -menu: - docs: - parent: 'getting-started' weight: 150 --- In production environments, your API may have to access a message broker that's protected by some auth mechanisms. -Some examples of these are: +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 most probably make use of 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. +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: '2.5.0' + +{`asyncapi: 3.0.0 info: title: Hello world application version: '0.1.0' servers: production: - url: broker.mycompany.com + host: broker.mycompany.com protocol: amqp description: This is "My Company" broker. security: - - user-password: [] + - type: userPassword channels: hello: - publish: - message: + address: 'hello' + messages: + sayHelloMessage: $ref: '#/components/messages/hello-msg' goodbye: - publish: - message: + 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: @@ -66,19 +134,14 @@ components: type: userPassword`} -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: - -1. There's a new property in the server object called `security`. It's an array and can contain multiple security mechanisms. You chose to add one called "user-password". This is simply a memorable name that you give to this `security` scheme. Whatever name you choose, it must be defined in the `components/securitySchemes` section. You might have also noticed its value is an empty array. That's because some security schemes allow for extra configuration. Since this is not the case in this example, leave the array empty. -2. We've added a new section called `securitySchemes` under `components`. Inside it, you can find the definition of your `user-password` mechanism. This section makes it clear that you're speaking about a `user/password` mechanism, which is the `type: userPassword` in line 44. - -There are many more security schemes. Learn more about them here. +Learn more about the several kinds of security schemes. ## Conclusion -You're now able to define what security mechanisms your application needs to connect to the server. You've seen how to define the requirement of a user and a password, which is the most common use case. +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. +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. diff --git a/pages/docs/tutorials/getting-started/servers.md b/pages/docs/tutorials/getting-started/servers.md index 32337395516..6bca604ebe6 100644 --- a/pages/docs/tutorials/getting-started/servers.md +++ b/pages/docs/tutorials/getting-started/servers.md @@ -9,42 +9,48 @@ 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 article, 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. +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: 2.5.0 + +{`asyncapi: 3.0.0 info: title: Hello world application version: '0.1.0' servers: production: - url: broker.mycompany.com + host: broker.mycompany.com protocol: amqp description: This is "My Company" broker. channels: hello: - publish: - message: + address: 'hello' + messages: + sayHelloMessage: payload: type: string - pattern: '^hello .+$'`} + 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`. This protocol is very common and was popularized by RabbitMQ (among others). We picked `amqp` for our example, but 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). +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, usually you specify the URL of the broker. +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 `Hello world application` connects to and you can start receiving `hello {name}` messages. +Now you know where the `Hello world application` connects to, and you can start receiving `hello {name}` messages. -In the next chapter, you'll learn how to add security requirements to your server. +In the next section, you'll learn how to add security requirements to your server. diff --git a/pages/docs/tutorials/message-validation.md b/pages/docs/tutorials/message-validation.md index e06d226b291..faea57f4a73 100644 --- a/pages/docs/tutorials/message-validation.md +++ b/pages/docs/tutorials/message-validation.md @@ -1,93 +1,110 @@ ---- -title: Message validation in runtime -description: In this tutorial, you'll learn how to validate AsyncAPI messages (events). - -weight: 130 ---- - -## Introduction -In this tutorial, you'll learn how to validate messages (events) that are sent to your AsyncAPI application. - -## Background context -Message validation can be performed at both the **producer** and **consumer** levels. Message validation requires the participation of the producer, consumer, and broker. We will learn how to validate messages at the consumer level by discarding invalid messages based on the parameters provided. - -You will be using the [Eclipse Mosquitto](https://mosquitto.org/) broker. The MQTT protocol provides a lightweight method of messaging using a publish/subscribe model. You will also use an MQTT client that runs an MQTT library and connects to an MQTT broker over a network. Here publishers and subscribers are MQTT clients. The publisher and subscriber labels refer to whether the client is publishing or subscribing to receive messages. - -In the previous tutorial, you generated your application using the [AsyncAPI Generator](https://github.com/asyncapi/generator) Node.js template. - - -If you did not follow the previous tutorial and do not have an `asyncapi.yaml` file ready, then generate one by running: -`asyncapi new --example=tutorial.yml --no-tty`. - -Next, generate a server by running: - - asyncapi generate fromTemplate asyncapi.yaml @asyncapi/nodejs-template -o output -p server=mosquitto - cd output && npm install - - - -Now you will be validating the messages which you will be sending to your application using a Mosquitto broker and an MQTT client. - -## Validate messages -In this step, you will send a message to your application using an MQTT broker and check the errors logged when you accidentally send an invalid message. - -1. Start your generated application. - - -{`npm start`} - - -2. Let's send a message: - - - {`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": "3", "sentAt": "2017-06-07T12:34:32.000Z"}'`} - - -Go back to the previous terminal and check if your application logged the streetlight condition you just sent, with errors related to the invalid message. You should see something displayed in the terminal similar to the following: - - - {`light/measured was received: -{ id: 1, lumens: '3', sentAt: '2017-06-07T12:34:32.000Z' } -❗ Message Rejected. data.lumens should be integer`} - - -Here, you can see that the property `lumens` has type `integer`, but you are sending a message with type `string`. - - - {` message: - name: lumensInfo - 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.`} - - -3. Send a correct message to your application: - - - {`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": 3, "sentAt": "2017-06-07T12:34:32.000Z"}'`} - - -You can see that your generated application received a message in the terminal: - - - {`light/measured was received: -{ id: 1, lumens: 3, sentAt: '2017-06-07T12:34:32.000Z' }`} - - -This indicates that your message is valid and the application recieved it correctly. - -## Summary -In this tutorial, you learned how to connect your generated application to an MQTT broker, send messages through it, identify when an invalid message is sent to your application, and how to correct an invalid message. - -## Next steps -Now that you've completed this tutorial, enjoy our [AsyncAPI message validation guide](https://www.asyncapi.com/docs/guides/message-validation). - ---- +--- +title: Message validation in runtime +description: In this tutorial, you'll learn how to validate AsyncAPI messages (events). + +weight: 130 +--- + +## Introduction +In this tutorial, you'll learn how to validate messages (events) that are sent to your AsyncAPI application. + +## Background context +Message validation can be performed at both the **producer** and **consumer** levels. Message validation requires the participation of the producer, consumer, and broker. We will learn how to validate messages at the consumer level by discarding invalid messages based on the parameters provided. + +You will be using the [Eclipse Mosquitto](https://mosquitto.org/) broker. The MQTT protocol provides a lightweight method of messaging using a publish/subscribe model. You will also use an MQTT client that runs an MQTT library and connects to an MQTT broker over a network. Here producers and consumers are MQTT clients. The producer and consumer labels refer to whether the client is sending or receiving messages. + +In the [previous tutorial, you generated an application](https://asyncapi.com/docs/tutorials/generate-code) that uses [Glee](https://github.com/asyncapi/glee) framework. Now you will be validating the messages that you will be sending to your application using a Mosquitto broker and an MQTT client. + + + +If you did not follow the previous tutorial and do not have an application generated, then follow these instructions: + + asyncapi new glee --name=tutorial --template tutorial`. + cd tutorial && npm install + + + +## Validate messages +In this step, you will send a message to your application using an MQTT broker and check the errors logged when you accidentally send an invalid message. + +1. Start your generated application: + + +{`npm run dev`} + + +2. Send a message: + + + {`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": "3", "sentAt": "2017-06-07T12:34:32.000Z"}'`} + + +Go back to the previous terminal and check if your application logged the streetlight condition you just sent, with errors related to the invalid message. You should see something displayed in the terminal similar to the following: + + + {`lightMeasured was received from mosquitto: +{ id: 1, lumens: '3', sentAt: '2017-06-07T12:34:32.000Z' } +x You have received a malformed event or there has been error processing it. Please review the error below: +TYPE should be integer + + 1 | { + 2 | "id": 1, +> 3 | "lumens": "3", + | ^^^ 👈🏽 type should be integer + 4 | "sentAt": "2017-06-07T12:34:32.000Z" + 5 | } + +ONEOF should match exactly one schema in oneOf + +> 1 | { + | ^ +> 2 | "id": 1, + | ^^^^^^^^^^ +> 3 | "lumens": "3", + | ^^^^^^^^^^ +> 4 | "sentAt": "2017-06-07T12:34:32.000Z" + | ^^^^^^^^^^ +> 5 | } + | ^^ 👈🏽 oneOf should match exactly one schema in oneOf`} + + +Here, you can see that the property `lumens` has type `integer`, but you are sending a message with type `string`: + + + {` message: + name: lumensInfo + 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.`} + + +3. Send a correct message to your application: + + + {`mqtt pub -t 'light/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": 3, "sentAt": "2017-06-07T12:34:32.000Z"}'`} + + +You can see that your generated application received a message in the terminal: + + + {`lightMeasured was received from mosquitto: +{ id: 1, lumens: 3, sentAt: '2017-06-07T12:34:32.000Z' } +Streetlight with id "1" updated its lighting information to 3 lumens at 2017-06-07T12:34:32.000Z.`} + + +Such a terminal message indicates that your message is valid and the application received it correctly. + +## Summary +In this tutorial, you learned how to connect your generated application to an MQTT broker, send messages through it, identify when an invalid message is sent to your application, and how to correct an invalid message. + +## Next steps +Now that you've completed this tutorial, enjoy our [AsyncAPI message validation guide](https://www.asyncapi.com/docs/guides/message-validation). + diff --git a/pages/docs/tutorials/streetlights-interactive.md b/pages/docs/tutorials/streetlights-interactive.md index 405dcee1d29..b28bcb2a407 100644 --- a/pages/docs/tutorials/streetlights-interactive.md +++ b/pages/docs/tutorials/streetlights-interactive.md @@ -1,17 +1,13 @@ --- -title: 'Streetlights - Interactive (Alpha)' +title: 'Streetlights - Interactive' description: Interactive version of the original Streetlights tutorial. weight: 180 --- ->tl;dr -Please try out [this](https://killercoda.com/asyncapi/scenario/streetlight-tut) interactive tutorial and let us know what you think, as we plan to have all the docs written this way. +> Check out the [Streetlights interactive tutorial](https://killercoda.com/asyncapi/scenario/streetlight-tut-v3); we plan to have more docs written this way! Our interactive tutorials on [KillerCoda](https://killercoda.com) work for everyone, regardless of your operating system. -We created an interactive tutorial using [KillerCoda](https://killercoda.com). It is another version of the [Streetlights](./streetlights.md) tutorial that will always work for you no matter what operating system you have. -Please become our alpha testers of the tutorial: - -1. Go through the tutorial [here](https://killercoda.com/asyncapi/scenario/streetlight-tut) -2. Let us know what you think using the channel that works for you the best: +1. Go through the [Streetlights interactive tutorial](https://killercoda.com/asyncapi/scenario/streetlight-tut-v3). +2. Share your opinion via your preferred channel: - [Slack](https://www.asyncapi.com/slack-invite/) - [Twitter](https://twitter.com/AsyncAPISpec) - [GitHub Issue](https://github.com/asyncapi/website/issues/) diff --git a/pages/docs/tutorials/studio-document-validation.md b/pages/docs/tutorials/studio-document-validation.md index 199189dfc28..91ea2a26b08 100644 --- a/pages/docs/tutorials/studio-document-validation.md +++ b/pages/docs/tutorials/studio-document-validation.md @@ -1,29 +1,23 @@ --- title: "Validate AsyncAPI document with Studio" -description: This tutorial will teach you how to validate AsyncAPI documents using the AsyncAPI Studio tool. +description: In this tutorial, you'll learn how to validate AsyncAPI documents using the AsyncAPI Studio tool. weight: 120 --- ## Introduction -This tutorial will teach you how to validate AsyncAPI documents using the [AsyncAPI Studio tool](https://studio.asyncapi.com/). +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 we end up with a valid AsyncAPI document. This process will illustrate how to identify [`REQUIRED` properties in AsyncAPI documents](https://www.asyncapi.com/docs/reference/specification/latest#A2SObject). +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. - - -If you did not follow the previous tutorial and do not have an `asyncapi.yaml` file ready, then generate one using `asyncapi new --example=tutorial.yml --no-tty` command. - - - 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 we have an invalid AsyncAPI document. +Let's pretend you have an invalid AsyncAPI document. 1. Open [Studio](https://studio.asyncapi.com/). @@ -36,23 +30,27 @@ You can also skip the step below by clicking on New File in Studio and opening t 2. Copy and paste the below invalid AsyncAPI document: ```yaml -asyncapi: '1.0.0' +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: mqtt://test.mosquitto.org + url: test.mosquitto.org protocol: mqtt + channels: - light/measured: - publish: - summary: Inform about environmental lighting conditions for a particular streetlight. - operationId: onLightMeasured - message: + lightMeasured: + address: 'light/measured' + messages: + lightMeasuredMessage: name: LightMeasured payload: type: object @@ -66,31 +64,38 @@ channels: minimum: 0 description: Light intensity measured in lumens. sentAt: - type: integer + 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 we end up with a valid AsyncAPI document. +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. +2. Open **DIAGNOSTICS**, you can see more information related to your errors. -3. Fix the incorrect AsyncAPI specification number to `2.5.0`. +3. Fix the incorrect server information. Use `host` instead of `url` ```yaml -asyncapi: '2.5.0' -info: - title: Account Service - version: 1.0.0 - ``` +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: `must be number`. Fix the `minimum` by changing it to: `0`. +4. Read the next error: `"minimum" property type must be number`. Fix the `minimum` by changing it to: `0`. ```yaml properties: @@ -98,30 +103,14 @@ Notice how description property is missing; that doesn't make the AsyncAP type: integer minimum: 0 ``` -5. You see three errors: -- must be equal to one of the allowed values -- must be array -- must match a schema in `anyOf` - -`anyOf` means it should match any one the above schemas then it is valid. - -Now let's fix this error by changing the type to `string` - -```yaml - sentAt: - type: string - format: date-time - description: Date and time when the message was sent. -``` - -6. Congratulations! You identified and fixed all the errors, and now have a valid AsyncAPI document. +5. Congratulations! You identified and fixed all the errors, and now have a valid AsyncAPI document. ## Summary -This tutorial taught us how to validate an AsyncAPI document using the AsyncAPI Studio tool. We also learned to troubleshoot an invalid AsyncAPI document by following the error message directions in diagnostics. In doing so, we learned how to identify `REQUIRED` properties in all AsyncAPI documents. +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)](https://asyncapi.com/docs/tutorials/generate-code) which you will be sending to your application. +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](https://asyncapi.com/docs/guides/validate). +You may also enjoy reading our [AsyncAPI document validation guide](/docs/guides/validate). --- diff --git a/pages/tools/cli.js b/pages/tools/cli.js index a6eab46fdec..8982f19b67c 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 diff --git a/pages/tools/parsers.js b/pages/tools/parsers.js index 4b8d6df7636..047c0038e52 100644 --- a/pages/tools/parsers.js +++ b/pages/tools/parsers.js @@ -55,7 +55,7 @@ export default function ParsersPage() { npm install @asyncapi/parser {renderButtons()}
- + {getCode()}
@@ -68,26 +68,32 @@ function getCode() { return `import { parse } from '@asyncapi/parser' const doc = await parse(\` - asyncapi: '2.6.0' - info: - title: Example - version: '1.0.0' - channels: - example-channel: - subscribe: - message: - payload: - type: object - properties: - exampleField: - type: string - exampleNumber: - type: number - exampleDate: - type: string - format: date-time +asyncapi: '3.0.0' +info: + title: Example + version: '1.0.0' +channels: + example: + address: example-channel + messages: + example: + payload: + type: object + properties: + exampleField: + type: string + exampleNumber: + type: number + exampleDate: + type: string + format: date-time +operations: + example: + action: send + channel: + $ref: '#/channels/example' \`) console.log(doc.info().title()) // => Example` -} \ No newline at end of file +} diff --git a/public/_redirects b/public/_redirects index 46ecc4f0e7a..21425ffb3f6 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.15 /docs/reference/specification/v3.0.0-next-major-spec.15 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! @@ -56,7 +53,7 @@ https://www.asyncapi.io/* https://www.asyncapi.com/:splat 301! /asyncapi-react https://asyncapi.github.io/asyncapi-react 301! # Slack -/slack-invite https://join.slack.com/t/asyncapi/shared_invite/zt-2329g7esz-jPKWhnRBX0NKJMK4gatqKQ 302! +/slack-invite https://join.slack.com/t/asyncapi/shared_invite/zt-27m89oa1t-ZC~UIa5B2Vujm6oq7fa~gQ 302! # Central Maven repository verification /OSSRH-63280 https://github.com/asyncapi/java-asyncapi 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 00000000000..eb5d0a6c127 Binary files /dev/null and b/public/img/posts/release-notes-3.0.0/cover.webp differ diff --git a/public/robots.txt b/public/robots.txt index a0b34874901..1ef1869a515 100644 --- a/public/robots.txt +++ b/public/robots.txt @@ -1,3 +1,3 @@ User-agent: * Disallow: /definitions/ -Disallow: /schema-store/ +Disallow: /schema-store/ \ No newline at end of file