feat: add info that protocol binding objects are extendable

[derberg]

Resolves #869

I wasn't sure what is the best way to specify it on binding level in the spec. Open to different ideas 🙏🏼

@fmvilas @char0n @dalelane @smoya

I will also open separate PR to bindings repo to make it clear there for every single binding

[dalelane]

This seems like a good approach to me

[char0n]

Hi @derberg,

The usual position for the sentence "This object MAY be extended with [Specification Extensions](#specificationExtensions)" is right after the list of fixed fields. In this PR you've changed this rule and IMHO this might bring future confusion. If I for example, as a tooling author, don't find this sentence right after the list of object fixed fields, I'll automatically assume object doesn't support the spec extensions. Consistency is the king ;]

---

Protocol-specific binding objects MAY be extended with Specification Extensions.

Regarding the above sentence - it might conflict with what the protocol specific binding objects actually demand (some demands no spec extensions). What would be the source of truth for this conflict resolution then? I'd assume the bindings overrides what AsyncAPI spec says.

IMHO the best solution would be to retain consistency and for every protocol specific binding object we should either add the already established This object MAY be extended with [Specification Extensions](#specificationExtensions) or not (if not suitable).

This would make it compatible with AsyncAPI spec and if protocol specific binding supports the spec extension, people will know where to find this information and will know what it means when this information is missing.

[derberg]

@char0n do you mean we do not need this PR and Protocol-specific binding objects MAY be extended with [Specification Extensions](#specificationExtensions). is not needed?

the goal of this sentence is to enforce a standard on all the bindings, that they need to be extensible, that it is not individual binding maintainer to disable extensions. If we do not have this here in the spec, how can we ensure it in bindings? this rule should be written in spec IMHO, not in some contribution guide in the bindings repo

---

and yeah, I totally agree that consistency matters, I just did not have a better idea. I do not know why but sometimes having below under the table with bindings list seemed strange to me:

This object MAY be extended with [Specification Extensions](#specificationExtensions).
Protocol-specific binding objects MAY be extended with [Specification Extensions](#specificationExtensions).

but now when I think of it, it looks good 😄

[char0n]

@char0n do you mean we do not need this PR and Protocol-specific binding objects MAY be extended with Specification Extensions. is not needed?

Yep, that's I'm trying to say.

the goal of this sentence is to enforce a standard on all the bindings, that they need to be extensible, that it is not individual binding maintainer to disable extensions. If we do not have this here in the spec, how can we ensure it in bindings? this rule should be written in spec IMHO, not in some contribution guide in the bindings repo

I understand your motivation, but IMHO this sentence tries to convey how new bindings should be constructed, which should be part of PR review process to make sure bindings are consistent and always include the This object MAY be extended with [Specification Extensions](#specificationExtensions) sentence.

I see also an ambiguity in Protocol-specific binding objects MAY be extended with [Specification Extensions](#specificationExtensions). - does this mean that protocol bindings which are currently reserved supports the extension or not?

You've already issued asyncapi/bindings#179, that handles extension on individual protocol binding level. Every binding object that can be extended with extension explicitly states that now. This is consistent with AsyncAPI spec itself and it should be enough for tooling authors.

---

Anyway I don't have strong opinion about this. If you leave the sentence there it's just fine. I was just trying to possibly bring a little bit more consistency and clarity, and eliminate ambiguity.

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
No Duplication information

[derberg]

Ok so what I did for now is moving info about binding extensibility back to its original location for consistency. The only change you can see is a new sentence about extensibility of specific binding object.

@dalelane @smoya @fmvilas
can you folks look on the message from @char0n ?

I'm in doubt. Cause yes, adding the info I suggest is weird. But on the other hand, we cannot just count on the PR review process and that having extensions enabled everywhere is just a matter of consistency. I think we need to have it written somewhere, and still think bindings repo contribution guide is not a place for that

[fmvilas]

I think it's totally fine to put it here.

[derberg]

@smoya can you also have a look please?