asyncapi / asyncapi/cli

[FEATURE] Support converting AsyncAPI documents to older versions (downgrades)

Open
#1,988 3 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
272
Forks
375
Avg merge
3h 22m
Merged PRs (30d)
8

Description

### Why do we need this improvement?

The `convert` command currently prevents converting AsyncAPI documents to older versions. When a target version lower than the source document version is specified, the conversion is explicitly blocked.

In real-world scenarios, teams often need to maintain backward compatibility with systems, tooling, or platforms that only support older AsyncAPI versions. The inability to downgrade documents makes it harder to integrate AsyncAPI into mixed or legacy environments and limits the flexibility of the conversion workflow.

### How will this change help?

Supporting controlled downgrades would make the `convert` command more flexible and useful in real-world adoption scenarios.

This would:
- Enable backward compatibility with systems that only support older AsyncAPI versions
- Improve migration workflows between AsyncAPI versions
- Allow teams to standardize on AsyncAPI while still supporting legacy consumers
- Make the CLI conversion feature more complete and predictable

Even partial or best-effort downgrades (with clear warnings) would be valuable for users.

### Screenshots

N/A – this is a CLI behavior limitation and does not involve UI output.

### How could it be implemented/designed?

Downgrade support could be implemented in a controlled and explicit way to avoid unexpected behavior.

Possible approaches include:
- Allowing downgrades behind an explicit flag (for example, `--allow-downgrade`)
- Performing best-effort conversion while emitting warnings for unsupported or incompatible fields
- Validating the downgraded document against the target AsyncAPI version schema
- Clearly documenting which elements can and cannot be safely downgraded

This approach would preserve backward compatibility while giving users the choice to opt into downgrade behavior.

### 🚧 Breaking changes

No

### 👀 Have you checked for similar open issues?

- [x] I checked and didn't find a similar issue

### 🏢 Have you read the Contributing Guidelines?

- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)

### Are you willing to work on this issue?

Yes I am willing to submit a PR!

Contributor guide

Open the contributing guide

Research direction

Start with the convert command and its current guard that blocks targets older than the source document version. Determine how an explicit downgrade option, compatibility warnings, and target-version validation should work; done means older AsyncAPI documents can be converted predictably without silently losing unsupported fields.

Written by the indexing model from the issue text.

Assessment

Tech stack
nodejs, typescript
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.