[FEATURE] Support converting AsyncAPI documents to older versions (downgrades)
- 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
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