Skip to content

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

@smoya

Description

@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:

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/typescriptSpecify what technical area given issue relates to. Its goal is to ease filtering good first issues.enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions