Figure out how to reduce friction between Binding versions and users of the Parser

[smoya]

This issue is WIP.

During the research and designing process for the new Intent-Driven Parser API, we noticed how rough is the interaction with Bindings. Bindings look like a complete mystery from the point of view of the Parser since there is no specific API or contract for interacting with them. They are basically key => value structures (even though the underlying structure is a schema). That makes the integration with tooling difficult and rough, with no structure or content type prediction, no validation, and zero comprehensive support from the user experience point of view unless you have full knowledge on how the Binding works and what the Binding looks like.

The current Parser forces the templates to potentially break when new breaking changes are introduced by a new Binding major version release. The reason behind this statement is that the underlying structure should be known in advance and access to it is made through particular fields that can differ between Binding versions.

For example: AMQP Binding version 1.0.0 could introduce a breaking change were the field method returns an array of possible methods rather than just one but also move the field under a new one called request so it becomes request.method This will make templates refactor their calls to binding.method to binding.request.method and also remember that the new returned type is an array now.

The issue relates to that fact but it is bigger in terms of complexity: How could the Parser API support all Bindings versions and, at the same time, be resilient to breaking changes within Bindings, so templates reduce breaking changes?

Option 1. Keep the parser act as it does now.

Meaning the bindings are just objects. The parser returns whatever it has and users of the parser (like templates) will keep managing breaking changes on their own when using Bindings.

Option 2. Spec is completely tied to binding versions, meaning every time a binding releases, the spec does as well.

The Parser will be tied to one or more Spec versions, and at the same time, each Spec version will point to specific Binding versions. We maintain a Binding support matrix with version ranges on the Spec side, ergo the Parser will also need to support those.

Option 3. Move bindings to be part of the actual spec instead of having their own release cycle.

Meaning a change in binding is a change to the spec. Very close to the previous option in terms of technical solutions.

Option 4. Bindings provide their own parser library, Intent-driven API for bindings.

For the breaking change example shown above, intent-driven API could help by just providing the binding.RequestMethod() intent to map to binding.method or binding.request.method depending on the binding version. Meaning users of the Parser won't suffer from breaking change on this use case.

Each binding will need to provide its own parser library, based on intents. Users of the parser would choose and provide somehow the library they want to use for parsing bindings. The parser should work within a common interface like Parse(object) : object.

In that way, templates (for example) will not care about the version of the binding used in the specific spec, and just will call the intent binding.RequestMethod().

[asyncapi-bot]

Hey! You've labeled this issue as a Scope. Remember you can use the following command to inform about its progress:

/progress <percentage> [message]

or

/progress <percentage>

A mutiline message.
It supports **Markdown**.

Example:

/progress 40 We're still figuring out how to implement this. We have an idea but it is not yet confirmed it will work.

/progress 50

A few notes:

* We got this figured out :tada:
* We're going to use [this library](#link-to-website) to avoid losing time implementing this algorithm.
* We decided to go for the quickest solution and will improve it if we got time at the end of the cycle.

---

:weight_lifting_woman: See the progress on the Shape Up Dashboard.

[derberg]

As mentioned at the meeting today, I think best is option 1 looking on the current complexity of work on intent API and unstable phase of bindings

[jonaslagoni]

I agree with @derberg we should just focus on the core spec. That being said, as bindings improve and become more stable I would assume that we could reuse a lot of the existing experience with the intent API and replicate this for bindings.

[smoya]

It seems we can move forward with Option 1 as some people agreed (I'm included). I'm gonna close this issue as I consider it solved, however, feel free to reopen if applies.

[smoya]

/progress 100 Agreed on following option 1, which is keeping the same behavior the current parser follows., meaning Bindings are accessed as plain objects.

[fmvilas]

I agree we stay on option 1 for now but it's an interesting debate nonetheless. My feeling is that —at some point— each binding could also provide an intent API themselves. I mean, at least the definition in a Markdown file. Like an implementation guide for the parsers.

[smoya]

My feeling is that —at some point— each binding could also provide an intent API themselves

@fmvilas That is what point 4 suggests (but providing full implementation).

[fmvilas]

Yeah, I mean just the definition not the implementation. Something that parsers can optionally implement.