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.

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

chore(blog): add release notes for 2.5.0 release #959

Merged
merged 45 commits into from
Sep 29, 2022
Merged
Changes from 2 commits
Commits
Show all changes
45 commits
Select commit Hold shift + click to select a range
dbd9530
chore(blog): add release notes for 2.5.0 release
char0n Sep 20, 2022
a4474e8
Update pages/blog/release-notes-2.5.0.md
char0n Sep 22, 2022
51e8be1
Merge branch 'asyncapi:master' into char0n/blog-release-2.5.0
char0n Sep 23, 2022
921056d
chore(blog): add section about tag server decoration
char0n Sep 23, 2022
712cd58
chore(blog): add section + placelhoder for IBMMQ binding
char0n Sep 24, 2022
e552d63
chore(blog): add section + placelhoder for IBMMQ binding
char0n Sep 24, 2022
6fa22b7
Merge branch 'asyncapi:master' into char0n/blog-release-2.5.0
char0n Sep 27, 2022
673b36d
chore(blog): add section about missing IBM MQ
char0n Sep 27, 2022
985cabd
chore(blog): add content placeholder for Google Cloud pub/sub bindings
char0n Sep 27, 2022
493886f
chore(blog): add content for Google Pub/Sub bindings
char0n Sep 28, 2022
8ff0271
chore: set release date for 29.9.2022
char0n Sep 28, 2022
a0e3b63
Merge branch 'master' into char0n/blog-release-2.5.0
char0n Sep 28, 2022
f320401
chore: set versions to tooling
char0n Sep 28, 2022
6892977
Merge remote-tracking branch 'origin/master' into char0n/blog-release…
char0n Sep 28, 2022
e35e2a3
chore: add AsyncAPI React Component
char0n Sep 28, 2022
03b36e9
Merge branch 'char0n/blog-release-2.5.0' of github.com:char0n/website…
char0n Sep 28, 2022
691c291
Merge branch 'master' into char0n/blog-release-2.5.0
quetzalliwrites Sep 28, 2022
d09bab3
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
d8e1142
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
bf3c2b9
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
fa4eda1
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
581b853
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
c75c5d1
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
f1a9306
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
89eea09
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
a86fbf6
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
56eb833
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
05aeb58
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
d6f66fb
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
f77f857
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
f8fd0b6
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
fcf0ea4
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
212c166
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
96620cf
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
3ed0872
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
ac84c20
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
e434b41
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
20769c0
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
2e812f1
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
3d1ea12
Update pages/blog/release-notes-2.5.0.md
char0n Sep 28, 2022
cf559da
Merge branch 'master' into char0n/blog-release-2.5.0
derberg Sep 29, 2022
5752058
Merge branch 'master' into char0n/blog-release-2.5.0
derberg Sep 29, 2022
541162f
Update pages/blog/release-notes-2.5.0.md
char0n Sep 29, 2022
035f484
Update pages/blog/release-notes-2.5.0.md
char0n Sep 29, 2022
1a2a6c6
Update pages/blog/release-notes-2.5.0.md
char0n Sep 29, 2022
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
94 changes: 94 additions & 0 deletions pages/blog/release-notes-2.5.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
---
title: AsyncAPI Spec 2.5.0 Release Notes
date: 2022-09-20T16:41:00+01:00
type: Communication
tags:
- Specification
- Release Notes
cover: /img/posts/release-notes-2.5.0/cover.webp
authors:
- name: Vladimír Gorej
photo: /img/avatars/char0n.webp
link: https://twitter.com/vladimirgorej
byline: Open Source Software Engineer, OSS contributor, author and content creator.
excerpt: "AsyncAPI 2.5 is now released. This brings really helpful additions, such as extended Server Variables reusability, and many clarifications"
char0n marked this conversation as resolved.
Show resolved Hide resolved
featured: true
---

The new version of the AsyncAPI specification - 2.5.0 - is now available.

> This is a minor release, and it doesn't bring any breaking changes. You can switch to it by modifying the following value in your AsyncAPI file `asyncapi: '2.4.0'` into `asyncapi: '2.5.0'`

## Server Variables can be now referenced from inside the Server Object

Previous AsyncAPI 2.4.0 release came with support of [defining Server Variable Objects as reusable components](https://www.asyncapi.com/blog/release-notes-2.4.0#server-variables-can-be-now-referenced-from-components).
char0n marked this conversation as resolved.
Show resolved Hide resolved
Unfortunately AsyncAPI 2.4.0 doesn't allow to reference reusable server variable objects from within the `Server Object`.
char0n marked this conversation as resolved.
Show resolved Hide resolved
So we ended up in a situation that reusable server variable objects can be defined, but they actually cannot be reused.
char0n marked this conversation as resolved.
Show resolved Hide resolved
AsyncAPI 2.5.0 remedies this deficiency by allowing to use `Reference Object` whenever `Server Variable Object` can be used inside `Server.variables` field.
char0n marked this conversation as resolved.
Show resolved Hide resolved

Following example is now fully compliant with the specification:
char0n marked this conversation as resolved.
Show resolved Hide resolved

```yaml
asyncapi: 2.4.0
servers:
development:
$ref: '#/components/servers/myserver'
production:
$ref: '#/components/servers/myserver'
components:
servers:
myserver:
url: "{stage}.my-server.com:{port}"
protocol: ws
variables:
stage:
$ref: "#/components/serverVariables/stage"
port:
$ref: "#/components/serverVariables/port"
serverVariables:
stage:
default: dev
port:
enum: [5000, 6000]
default: 5000
```

This new feature was contributed by [Vladimír Gorej](https://github.com/char0n). For more detail, see [Vladimír's `/spec #776` pull request](https://github.com/asyncapi/spec/pull/776) and the [GitHub issue where Vladimír's change to `serverVariables ` was discussed](https://github.com/asyncapi/spec/issues/775).
char0n marked this conversation as resolved.
Show resolved Hide resolved

## Decorating Server Object with tags

placeholder for description
char0n marked this conversation as resolved.
Show resolved Hide resolved

## Clarifications

Here are notable clarifications that got into AsyncAPI 2.5.0 release. Here is the list of notable clarifications that may have
impact on the tooling authors:
char0n marked this conversation as resolved.
Show resolved Hide resolved

**ChannelItem.$ref resolution rules**

All references of `MUST be in the format of a URL` sentence have been substituted with `This MUST be in the form of an absolute URL`.
The meaning of `absolute URL` is now defined by [RFC3986, section 4.3](https://datatracker.ietf.org/doc/html/rfc3986#section-4.3).

**Clarification around URL resolution rules**

The resolution rules around `ChannelItem.$ref` field were not clearly defined. AsyncAPI 2.5.0 comes with explicit clarification
that the resolution is done as defined by the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03).
char0n marked this conversation as resolved.
Show resolved Hide resolved

## Tooling support

The following official AsyncAPI tools are already updated to support 2.5.0 version of the specification:
char0n marked this conversation as resolved.
Show resolved Hide resolved
- JSON Schema that supports validation of AsyncAPI documents is updated in [this](https://github.com/asyncapi/spec-json-schemas) repository. Also **@asyncapi/specs** package has been updated on NPM to version `<version>`, and it contains the JSON Schema document for AsyncAPI Spec 2.5.0.
- [JavaScript Parser](https://github.com/asyncapi/parser-js/) uses latest **@asyncapi/specs** package and can be used to parse and validate 2.5.0 documents. Upgrade to `<version>` version.
- [HTML template](https://github.com/asyncapi/html-template) uses the latest **@asyncapi/react-component** package. Upgrade to `<version>` version.
- [JavaScript Converter](https://github.com/asyncapi/converter-js/) enables conversion from any AsyncAPI version into the 2.5.0 version of the spec. Upgrade to `<version>` version.
- [Generator](https://github.com/asyncapi/generator/) uses the latest @asyncapi/parser package, so while generating output, it can validate 2.5.0 documents. Upgrade to `<version>` version.

char0n marked this conversation as resolved.
Show resolved Hide resolved
char0n marked this conversation as resolved.
Show resolved Hide resolved
Last but not least is the AsyncAPI Studio. [Check out the Studio with this example](https://studio.asyncapi.com/?url=https://raw.githubusercontent.com/asyncapi/spec/v2.5.0/examples/websocket-gemini.yml).
char0n marked this conversation as resolved.
Show resolved Hide resolved

## Look ahead

We aim to have a regular cadence of releases of the AsyncAPI specification, four times a year. For more information about when to expect future releases, you can see our [release process document](https://github.com/asyncapi/spec/blob/master/RELEASE_PROCESS.md#release-cadence).
char0n marked this conversation as resolved.
Show resolved Hide resolved

We're also working on the next major release of the AsyncAPI specification: 3.0.0. If you'd like to contribute, or just follow the discussions, you can see [Work on 3.0 release issue](https://github.com/asyncapi/spec/issues/691).
char0n marked this conversation as resolved.
Show resolved Hide resolved

> Photo by <a href="https://unsplash.com/@jeremythomasphoto?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Jeremy Thomas</a> on <a href="https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a>
Binary file added public/img/avatars/char0n.webp
Binary file not shown.
Binary file not shown.