AsyncAPI spec v3 support in CLI

[jonaslagoni]

Reason/Context

This Issue is used to track changes needed to support AsyncAPI v3. As a code owner, please edit this list of TODO tasks in order to properly track the progress 🙂 Once this issue is closed it means that v3 is now fully supported in this library.

Potentially, disable certain commands if they don't support v3.

Scope

• AsyncAPI spec v3 support in parser-js parser-js#780
• AsyncAPI spec v3 support in Modelina modelina#1376
• AsyncAPI spec v3 support in generator generator#979
• AsyncAPI spec v3 support in Bundler bundler#133
• AsyncAPI spec v3 support in Diff diff#154
• AsyncAPI spec v3 support in Optimizer optimizer#168
• AsyncAPI spec v3 support in Studio studio#641
• AsyncAPI spec v3 support in Cupid asyncapi-archived-repos/cupid#171
• Support converting to 3.0.0 converter-js#110
• Update all dependencies once they suppport v3

[jonaslagoni]

@Souvikns @magicmatatjahu @derberg @boyney123 would it make sense add something like the following check for each command:

if(document.asyncapi === '3.0.0') { throw new Error('This command does not support AsyncAPI v3 yet, please see https://github.com/asyncapi/xxxxx/issues/xx')}

And then we can remove that check once the dependency has been updated with support for v3 in the specific tools?

That way we don't need any feature branch, nor worry about weird error codes from commands when you try to use an AsyncAPI v3 document for commands that don't yet support it.

[magicmatatjahu]

@jonaslagoni Rather than throwing error we can inform (by some warning) about alpha support for 3.0 to test it earlier, so people can use cli for 3.0, however with the knowledge that something doesn't work/isn't supported/has bugs.

[jonaslagoni]

@jonaslagoni Rather than throwing error we can inform (by some warning) about alpha support for 3.0 to test it earlier, so people can use cli for 3.0, however with the knowledge that something doesn't work/isn't supported/has bugs.

So instead of stopping the call in it's track, you want to warn people that it might or might not work?

[magicmatatjahu]

@jonaslagoni Exactly.

EDIT: However, having thought about it, your idea makes more sense. As there will be support in tolling we can immediately remove this error for the given command.

[jonaslagoni]

I am gonna prepare a PR tomorrow unless other join the discussion 🙂

[Souvikns]

Yeah, I think we can throw a warning instead of an error for now, all command throws a warning but once the command is updated for 3.0 we can just remove the warnings for that command.

[derberg]

I'm immediately thinking how we can automate it, instead of manually adding warning/error where needed, then manually removing it. Maybe we can figure out a different way 🤔 Like an asyncapi property in a package, that says what versions it supports? so we have a generic solution that checks that flag and drops warning/error or not 🤔

[jonaslagoni]

@derberg I am all for automation, however for v3, I would stick with just failing the commands if v3 is not supported 😄 That way we don't have to rush into a solution but could target it for any next major versions of the spec.

[derberg]

@jonaslagoni yeah, definitely, I mean that instead of hardcoding it in CLI, we can agree on a setting in package.json of other dependencies, that we will have asyncapi property there (like we have with generator config). So in CLI we simply write a code:

• user runs command
• we fetch their asyncapi document
• check version
• check core package and its package.json if asyncapi is there
  • if asyncapi is there, we check version it supports
  • if asyncapi version do not have the version on the list, then fail
  • if asyncapi props is not there, we know it is a new thing and if package maintainer did not add it, it means it is not supporting given version

asyncapi key in package.json could be an array of versions, following semantic versioning rules that already work in dependencies with ^ and all these things.

we already have similar thing in generator, so your template can say what generator version it works with, why not have an option what asyncapi document your package works with 🤔

[jonaslagoni]

All makes sense to me 😄 Great to have for next major release 💪

[derberg]

wait wait, are you having some personal goal to work on your assertiveness skills 😆

Great to have for next major release 💪

you know it doesn't make sense, right? right? 😆

---

it is an easy thing to do, we just need to agree on how should such an info be presented in package.json. If you are afraid that you will have to do it and drive discussion then I officially, hereby, confirm that I do not expect you do it 😄 and that I can start the public discussion and drive it forward 🍻

[jonaslagoni]

hereby, confirm that I do not expect you do it 😄 and that I can start the public discussion and drive it forward 🍻

Haha, please do then 💪 🎉

[Souvikns]

@derberg I like this idea of having flags at the library level to prevent CLI from running the command and outputting meaningful error messages if the library does not support the current spec version. I want to help build this. I watched https://www.youtube.com/watch?v=hc0Lxr3G8T4 and what I understood is that we do hardcoding now but then update it in the future.

So for now we:

• Create an error in the problem library
• then write a check in each library (implemented by CLI) to throw this error
• Update CLI to check for this error and show suitable error messages, (or maybe we don't need to do this and show the error thrown by the library itself)

Let me know how I can get started with this, also should we move this to a separate issue?

[derberg]

@Souvikns best would be to start new issue

[smoya]

FIrst iteration on supporting v3 for validating docs #770

[cykl]

asyncapi/bundler#133 is marked as done and bundler 0.4.0 has been integrated into latest cli releases.

Is it expected that cli still display Error: One of the files you tried to bundle is AsyncAPI v3 format, the bundle command does not support it yet, please checkout https://github.com/asyncapi/bundler/issues/133? It's unclear to me if the explicit check introduced by #697 should be removed or if will be removed once all commands support v3.

Anyway, it's confusing for users.

[jonaslagoni]

@cykl if you have a spare minute please help remove the hard coded check if the bunder support it and have been updated here ✌️

[Amzani]

@jonaslagoni I think we can close this as https://github.com/asyncapi-archived-repos/cupid is archived

[jonaslagoni]

Lets close as soon as we enable v3 for Modelina in #1376