Adopt and/or adapt Spectral rules from AsyncAPI v2 Core ruleset to v3

[smoya]

Context

Spectral rules are the rules that validate AsyncAPI documents. There are different types or levels:

• Core ruleset. Basic but required validation. Apply to both v2 and v3 (with some exceptions).
• Recommended ruleset. Just like good practices. Those won't create validation errors but warnings. Apply to only v2 documents. Not very clear if we want to add for v3 and forward.
• Specific rulesets per AsyncAPI Spec version. Contain particular rulesets that apply only to documents of a particular Spec version.:
  • Core rulesets: Rules that are important and a doc of this Spec version must fulfil.
  • Recommended rulesets: Best practices for this particular Spec version

In the case of AsyncAPI Spec v3, the rules that apply ATM are:

• Core ruleset:
  • asyncapi-is-asyncapi - The input must be a document with a supported version of AsyncAPI.
  • asyncapi-latest-version - Checking if the AsyncAPI document is using the latest version.
  • asyncapi-document-resolved - Checking if the AsyncAPI document has valid resolved structure.
  • asyncapi-document-unresolved - Checking if the AsyncAPI document has valid unresolved structure.
  • asyncapi-internal - That rule is internal to extend Spectral functionality for Parser purposes.
• V3 specific ruleset:
  • V3 Core rulesets:
    • asyncapi3-operation-messages-from-referred-channel - Operation "messages" must be a subset of the messages defined in the channel referenced in this operation.
    • asyncapi3-required-operation-channel-unambiguity - The "channel" field of an operation under the root "operations" object must always reference a channel under the root "channels" object.
    • asyncapi3-required-channel-servers-unambiguity - The "servers" field of a channel under the root "channels" object must always reference a subset of the servers under the root "servers" object.

Description

If you check how many specific v2 rules are, you will notice a lot compared to v3. This PR tries to fix that gap between Spec versions and adopt or adapt those rules from v2 that make sense in v3. We will be focusing on Core rules and skip Recommended rules by now (we will work on it in a next iteration).

Core Rules we might want to adopt/adapt from v2 to v3:

• Create the rule asyncapi3-server-variables for the v3 core ruleset #1017
• Create the rule asyncapi3-channel-no-query-nor-fragment for the v3 core ruleset #1018
• Create the rule asyncapi3-channel-parameters for the v3 core ruleset #1019
• Create the rule asyncapi3-channel-servers for the v3 core ruleset #1020
• Create the rule asyncapi3-operation-operationId-uniqueness for the v3 core ruleset #1021
• Create the rule asyncapi3-message-messageId-uniqueness for the v3 core ruleset #1022
• Create the rule asyncapi3-tags-uniqueness for the v3 core ruleset #1023
• Create the rule asyncapi3-message-examples for the v3 core ruleset #1024
  • Discussion about this happening at fix: always allow schema string examples #1007

Discarded rules:

• asyncapi2-server-security - Server have to reference a defined security schemes.
  • No need since v3 Spec got a rewrite and removed the concept of Security Requirements. Now Security Schemes are specified directly into the security field.
• asyncapi2-operation-security - Operation have to reference a defined security schemes.
  • Discarded because of the same reasons as asyncapi2-server-security

[smoya]

bounty/candidate

[aeworxet]

Bounty Issue's service comment

Text labels: bounty/2024-Q3, bounty/medium, bounty/coding, bounty/unpicked, bounty/eol
First assignment to third-party contributors: 2024-06-21 00:00:00 UTC+12:00
End Of Life after: 2024-07-31 23:59:59 UTC-12:00

@asyncapi/bounty_team

The Bounty Program is not a Mentorship Program. The accepted level of Bounty Program Participants is Middle/Senior.

Third-party contributors should coherently articulate how they are going to approach the resolution process when expressing a desire to work on this Bounty Issue.

[ibishal]

• For rule asyncapi server variables it will be mostly mostly similar to asyncapi2-server-variables except in the input schema in place of url there should be host and pathname with type string, and in the variables, in parsedUrlVariables pass host+ pathname.

• asyncapi3-channel-no-query-nor-fragment it will be similar to asyncapi2-channel-no-query-nor-fragment

• asyncapi3-channel-parameters it is mostly done in my PR(fix: parser will throw an error when address is null/no param but param is present #1011 ), though i need to add the rules and its corresponding function in v3

• asyncapi3-channel-servers for this we need to create a function that will retrieve the keys (names) of the servers defined in the servers object, then we need to Iterate over each channel in the channels object, and if the server name is not defined push the error
  msg to the result array

cc @smoya (here is a brief outline of the first four rule)

[smoya]

@ibishal I read your DM's where you share what your contributions to AsyncAPI are, and I determined that this task requires a bit more of experience with not only the Parser but within the spec.

Not really sure you are the right candidate for this to work as a bounty issue, but feel free to submit PR's if you want to still work on it outside the bounty.
Happy to discuss if you truly believe I'm making a mistake here.

[aeworxet]

feel free to submit PR's if you want to still work on

OTHER ISSUES

outside the bounty.

If @ibishal wants to contribute, they can submit PRs for OTHER ISSUES, leaving the Bounty Issue intact, in order not to pollute its pristineness.

[smoya]

If @ibishal wants to contribute, they can submit PRs for OTHER ISSUES, leaving the Bounty Issue intact, in order not to pollute its pristineness.

Reiterating what I mentioned to @ibishal here, any user is encouraged to work on any of the issues available, no matters if they belong to an unassigned Bounty. That doesn't mean those issues will be assigned ever to the user since we only assign issues in programs such as Bounty, GSoC, etc.
Once a Bounty issue is assigned, any other PR sent in parallel regarding that issue will be discarded but only if that Bounty issue is assigned. If the issue is not assigned yet, why would I stop someone from contributing to it?

At least this is how I see it as maintainer of this repo.

cc @jonaslagoni @magicmatatjahu just in case they wanna share their opinion on this

[aeworxet]

@smoya

If a regular contributor made a PR addressing 10/100 of a Medium Bounty Issue, this already erodes the initial Complexity Level of the Bounty Issue with which it was submitted and accepted into the Bounty Program. Not talking about 20/100 or even 50/100.

So, to avoid the impact of this period between the assignment of the GitHub label bounty and the assignment of the Bounty Issue to a Bounty Program Participant of three (3) days, I would propose to stop accepting PRs starting from the moment of assignment of the GitHub label bounty (which I intentionally made unambiguous, dependent on the unchangeable GitHub timestamp) and not starting from the moment of the assignment of the Bounty Issue to a Bounty Program Participant.

The idea behind the Bounty Program is that there is one Bounty Program Participant and one AsyncAPI Maintainer, so it's clearly understandable who solved the Bounty Issue and therefore who should be rewarded for it.

cc @derberg

[aeworxet]

In other words, acceptance of PRs between the moment of assignment of the GitHub label bounty and the moment of assignment of the Bounty Issue to a Bounty Program Participant creates a race condition for the Bounty Program, which I obviously try to avoid by shifting mutex earlier in the execution sequence.

[smoya]

In other words, acceptance of PRs between the moment of assignment of the GitHub label bounty and the moment of assignment of the Bounty Issue to a Bounty Program Participant creates a race condition for the Bounty Program, which I obviously try to avoid by shifting mutex earlier in the execution sequence.

As shared via DM with you @aeworxet, I believe this topic deserves a proper discussion, and in another place rather than this issue. I'm happy to contribute to that discussion and express my concerns. I think this discussion should involve maintainers of other repos as well.

[aeworxet]

This Bounty Issue was not picked up for resolution by any Bounty Program Participant before the End Of Life, so it has been removed from the Bounty Program calendar quarter round 2024-Q3.