Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: adding document for extending the AsyncAPI specification #2407

Merged
merged 4 commits into from
Dec 16, 2023
Merged

docs: adding document for extending the AsyncAPI specification #2407

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ee2f9fa
add extend specification
mhmohona Dec 8, 2023
3ee0719
Update extending-specification.md
derberg Dec 13, 2023
435128a
Merge branch 'master' into spec-new
quetzalliwrites Dec 16, 2023
97a1116
tw editorial fixes
quetzalliwrites Dec 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions pages/docs/concepts/asyncapi-document/extending-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: Extending specification
weight: 240
---

Extending the AsyncAPI specification allows you to include specific information for your domain or use case that's not currently supported by the original specification or the protocol bindings. Extension capability allows for customization, making it possible to integrate unique aspects into APIs that the standard AsyncAPI specification doesn't normally accommodate.

## Specification extensions

The AsyncAPI Specification allows the addition of custom properties through patterned fields prefixed with an `x-`. That way, you can create unique things without causing problems in future updates.

The `x-` prefix is used to define custom properties. These properties are user-defined and won't conflict with future specification versions because any property starting with `x-` is reserved for user definitions.

Extensions can be used in any part of the AsyncAPI document.

Here is an example of how to extend the AsyncAPI document with a custom property:

```yml
asyncapi: 3.0.0
info:
title: Cool Example
version: 0.1.0
x-linkedin: '/company/asyncapi'
```

The above document shows an `info` object extended with custom information about a company's LinkedIn account that owns the application. Custom information is represented via a custom property called `x-linkedin`.

<Remember>
AsyncAPI tools might not support AsyncAPI extensions. Our tools can be extended to understand and handle the added data, especially if the tools are internal or open source.
</Remember>

## Extending unsupported features

If you need a feature not covered by the AsyncAPI specification, you can create an extension for it. Should this extension be useful to others, consider contributing it back to the AsyncAPI community. You can do this by [opening a spec issue](https://github.com/asyncapi/spec) in the AsyncAPI GitHub repository. Before contributing, review the [AsyncAPI contribution guidelines](https://github.com/asyncapi/spec/blob/master/CONTRIBUTING.md).