APIAddicts AsyncAPI Style Guide - Spectral Ruleset

Spectral rules for AsyncAPI 2.x and 3.x definitions, managed by ApiQuality and provided to the APIAddicts community.

Based on the SonarQube rules from sonarasyncapi-rules and following the same conventions as apiaddicts-style-guide-spectral (OpenAPI).

Quick Start

Prerequisites

• Node.js 18+ (LTS recommended)
• Spectral CLI: npm install -g @stoplight/spectral-cli

Installation

# Clone the repository
git clone https://github.com/apiaddicts/apiaddicts-asyncapi-style-guide-spectral.git
cd apiaddicts-asyncapi-style-guide-spectral
npm install

Usage

Command Line

# Lint a local AsyncAPI file
spectral lint -r asa-spectral.yaml your-asyncapi.yaml

# Lint using remote ruleset
spectral lint -r https://raw.githubusercontent.com/apiaddicts/apiaddicts-asyncapi-style-guide-spectral/main/asa-spectral.yaml your-asyncapi.yaml

Spectral Config File

Create a .spectral.yaml in your project root:

extends:
  - https://raw.githubusercontent.com/apiaddicts/apiaddicts-asyncapi-style-guide-spectral/main/asa-spectral.yaml

Then run:

spectral lint your-asyncapi.yaml

VSCode Extension

1. Install the Spectral VSCode extension.
2. Create a .spectral.yaml file as shown above.
3. Open any AsyncAPI YAML/JSON file for real-time linting.

Rules Reference

Security Rules

| Rule | Severity | Description | |------|----------|-------------| | AAR001 | error | HTTPS protocol (or equivalent secure protocol) is mandatory for all servers. | | AAR008 | error | The servers section must be defined in the AsyncAPI document. | | AAR018 | warn | Security schemes must be among allowed types and must be complete (all required fields). | | AAR043 | warn | Each channel operation should define a security scheme. |

Operations Rules

| Rule | Severity | Description | |------|----------|-------------| | AAR009 | error | Each operation (publish/subscribe) must declare at least one tag. | | AAR010 | warn | All tags should have a description field. | | AAR040 | warn | Channel servers must reference servers defined in the root servers object. | | AAR041 | info | Servers and channels should be defined in components for reusability. |

Format / Documentation Rules

| Rule | Severity | Description | |------|----------|-------------| | AAR011 | warn | License should be documented in info.license. | | AAR012 | warn | Each operation must have a unique operationId. | | AAR013 | error | No two operations may share the same operationId. | | AAR015 | warn | The info object must contain a contact section. | | AAR016 | warn | Contact must include name, url, and email fields. | | AAR017 | warn | The license object must have a url field. | | AAR019 | warn | The AsyncAPI document should define a unique id field. | | AAR021 | warn | Each operation must have a summary field. | | AAR022 | warn | Operation description must differ from its summary. | | AAR029 | warn | Each channel and operation must have a description. | | AAR032 | warn | Numeric properties must have minimum, maximum, or format restrictions. | | AAR033 | warn | String properties must have minLength, maxLength, pattern, or enum restrictions. | | AAR034 | warn | Numeric types must specify a valid format (int32, int64, float, double). | | AAR035 | info | Messages should have a title field. | | AAR036 | warn | Descriptions must begin with a capital letter and end with a period. | | AAR037 | warn | Bindings must specify a bindingVersion. | | AAR042 | info | Messages should have a unique messageId identifier. |

Schema Rules

| Rule | Severity | Description | |------|----------|-------------| | AAR024 | warn | Messages must comply with the payload schema (examples validated). | | AAR026 | info | Message schemas should be defined in components.messages and referenced via $ref. | | AAR031 | warn | Message examples must follow the declared payload and headers schemas. |

AsyncAPI Version Support

All rules support AsyncAPI 2.x by default. Rules that differ structurally for AsyncAPI 3.x have dedicated -v3 variants that are automatically applied based on the document format. Key differences handled:

• AsyncAPI 2.x: Operations are under channels[*].publish / channels[*].subscribe
• AsyncAPI 3.x: Operations are under operations[*] (top-level)

Custom Functions

The ruleset includes 9 custom Spectral functions for complex validation logic:

| Function | Used by | Purpose | |----------|---------|---------| | asa-check-security-schemes | AAR018 | Validates security scheme types and completeness | | asa-description-format | AAR036 | Checks description starts uppercase, ends with period | | asa-duplicate-operation-id | AAR013 | Detects duplicate operationId values across channels | | asa-message-examples-validation | AAR024, AAR031 | Validates message examples against schemas | | asa-numeric-parameter-integrity | AAR032 | Checks numeric properties have constraints | | asa-string-parameter-integrity | AAR033 | Checks string properties have constraints | | asa-channel-servers-defined | AAR040 | Validates channel server references exist | | asa-binding-version | AAR037 | Checks bindings have bindingVersion | | asa-message-schemas-in-components | AAR026 | Recommends $ref usage for message schemas |

Project Structure

apiaddicts-asyncapi-style-guide-spectral/
├── .github/workflows/       # CI/CD configuration
├── functions/               # Custom Spectral rule functions
│   ├── asa-binding-version.js
│   ├── asa-channel-servers-defined.js
│   ├── asa-check-security-schemes.js
│   ├── asa-description-format.js
│   ├── asa-duplicate-operation-id.js
│   ├── asa-message-examples-validation.js
│   ├── asa-message-schemas-in-components.js
│   ├── asa-numeric-parameter-integrity.js
│   └── asa-string-parameter-integrity.js
├── test/
│   ├── helpers/utils.js     # Test utilities
│   ├── asyncapi2/           # AsyncAPI 2.x tests
│   │   ├── security/        # Security rule tests
│   │   ├── operations/      # Operations rule tests
│   │   ├── format/          # Format/documentation tests
│   │   └── schemas/         # Schema rule tests
│   └── asyncapi3/           # AsyncAPI 3.x tests
├── asa-spectral.yaml        # Main Spectral ruleset
├── package.json
├── CONTRIBUTING.md
└── README.md

Running Tests

# Run all tests with coverage
npm test

# Run a specific test file
npx jest test/asyncapi2/security/aar001.test.js

Mapping to SonarQube Rules

This Spectral ruleset is a direct translation of the sonarasyncapi-rules SonarQube plugin. The mapping is:

| SonarQube Rule | Spectral Rule | SonarQube Type | SonarQube Severity | |----------------|---------------|----------------|-------------------| | AAR001 | asa:AAR001 | VULNERABILITY | CRITICAL | | AAR008 | asa:AAR008 | VULNERABILITY | CRITICAL | | AAR009 | asa:AAR009 | BUG | BLOCKER | | AAR010 | asa:AAR010 | BUG | MAJOR | | AAR011 | asa:AAR011 | BUG | MAJOR | | AAR012 | asa:AAR012 | BUG | MAJOR | | AAR013 | asa:AAR013 | BUG | MAJOR | | AAR015 | asa:AAR015 | BUG | MAJOR | | AAR016 | asa:AAR016 | BUG | MAJOR | | AAR017 | asa:AAR017 | BUG | MAJOR | | AAR018 | asa:AAR018 | VULNERABILITY | MAJOR | | AAR019 | asa:AAR019 | BUG | MAJOR | | AAR021 | asa:AAR021 | BUG | MAJOR | | AAR022 | asa:AAR022 | BUG | MAJOR | | AAR024 | asa:AAR024 | BUG | MAJOR | | AAR026 | asa:AAR026 | BUG | MAJOR | | AAR029 | asa:AAR029 | BUG | MAJOR | | AAR031 | asa:AAR031 | BUG | MAJOR | | AAR032 | asa:AAR032 | BUG | MAJOR | | AAR033 | asa:AAR033 | BUG | MAJOR | | AAR034 | asa:AAR034 | BUG | MAJOR | | AAR035 | asa:AAR035 | BUG | MAJOR | | AAR036 | asa:AAR036 | BUG | MAJOR | | AAR037 | asa:AAR037 | BUG | MAJOR | | AAR040 | asa:AAR040 | BUG | MAJOR | | AAR041 | asa:AAR041 | BUG | MAJOR | | AAR042 | asa:AAR042 | BUG | MAJOR | | AAR043 | asa:AAR043 | VULNERABILITY | MAJOR |

Related Projects

• apiaddicts-style-guide-spectral - Spectral rules for OpenAPI (OAR rules)
• sonarasyncapi-rules - SonarQube plugin for AsyncAPI (source rules)
• SonarAPI Rules - SonarQube plugin for OpenAPI

License

This project is licensed under the GPL-3.0 License.

Contributors

Managed by ApiQuality for the APIAddicts community.

Contributions are welcome! See CONTRIBUTING.md for guidelines.