npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@apiaddicts/asyncapi-style-guide-spectral

v2.1.1

Published

Spectral ruleset for AsyncAPI definitions by APIAddicts / ApiQuality

Readme

APIAddicts AsyncAPI Style Guide - Spectral Ruleset

Node.js CI Coverage License: GPL-3.0

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/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/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/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

Each rule is documented, with noncompliant and compliant examples for AsyncAPI 2.x and 3.x, in docs/resources (docs/resources/AARxxx.md).

Security Rules

| Rule | Severity | Description | |------|----------|-------------| | AAR001 | error | Server protocols must match the secure protocol pattern (pattern; default ^(https\|wss\|amqps\|kafka-secure\|secure-mqtt)$). | | 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. | | AAR064 | error | In the Kafka context, each server protocol must be kafka or kafka-ssl (not https, wss, etc.). | | AAR081 | error | Server names must match the configured naming pattern (default: letters, digits, - and _). | | AAR082 | error | Server names must start with an approved server type, alone or followed by - or _ (default: eventstreams, kafka). | | AAR083 | error | Server hosts must match the enterprise host pattern (default: quality.es or one of its subdomains). | | AAR084 | error | Server protocols must be allowed transport protocols (configurable via allowed-protocols; default: every AsyncAPI protocol). | | AAR085 | error | Server protocolVersion values must be approved versions (default: 3.3.0). | | AAR086 | error | Every server must declare a non-empty url or host, protocol and protocolVersion. | | AAR089 | error | Security schemes applied by servers and operations must be of approved types (default: scramSha512, X509). |

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. | | AAR053 | error | Channel/topic name must follow the corporate naming pattern <cod_poaps>.<classification>.<domain>.<origin>.<scope>[.<version>]. | | AAR054 | error | Channel/topic classification (2nd segment) must be cdc, cmd or sys. | | AAR057 | error | At least one channel must be documented as an error topic following <topicOriginal>.[<consumerGroup>.]error.<n>. | | AAR058 | warn | If a channel name contains .retry., it must follow <topicOriginal>.<consumerGroup>.retry.<n>. | | AAR061 | warn | Producing and consuming operations must share the same x-scs-function-name so the JAPI generator links them as one processor. | | AAR062 | error | Each consuming operation (v2 subscribe, v3 receive) must declare a consumer group via x-scs-group or bindings.kafka.groupId. | | AAR087 | error | Every channel must declare address (null if dynamic), a non-empty description and messages (2.x: description and a publish or subscribe operation). | | AAR088 | error | Every channel must list at least one server of the root servers object. | | AAR090 | error | Every channel must declare a kafka binding. | | AAR091 | error | A 3.x channel's messages must include at least one message. | | AAR092 | error | Every operation must declare a non-empty action, channel and summary (2.x: summary). | | AAR093 | error | Every operation must declare a kafka binding, directly or through its traits. | | AAR094 | error | Every operation must declare at least one message (2.x: in message; a 3.x operation without messages takes its channel's). |

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 an 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 declare a value restriction (minimum, maximum, format, enum or const). | | AAR033 | warn | String properties must declare a value restriction (minLength, maxLength, pattern, enum, const or format). | | 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. | | AAR050 | error | The info.title field must exist and not be empty. | | AAR051 | error | Every operation's operationId must be present and follow camelCase naming convention. | | AAR063 | error | The root asyncapi version must be one of the versions allowed by the organization (configurable via allowedVersions; default 2.6.0,3.0.0,3.1.0). | | AAR065 | warn | Message identifiers (messageId in 2.x, message key in 3.x) and message names must follow the configured naming convention (default camelCase). | | AAR066 | warn | Tag names must follow the configured naming convention (default kebab-case). | | AAR068 | error | Binding keys must be protocols from the allowed list that exist in the document's AsyncAPI version. | | AAR069 | error | Protocol bindings must declare the fields required for their protocol, optionally conditioned on a binding field. | | AAR070 | error | Every bindingVersion must match the configured pattern (default: a semantic version such as 0.4.0). | | AAR071 | warn | Every message must provide at least one example with a payload (or headers when it has no payload). | | AAR073 | warn | Every message must apply at least one message trait and every configured required-traits (default: none). | | AAR075 | error | The info object must declare a non-empty title, version and description. | | AAR076 | error | Every Tag object must declare a non-empty name and description. | | AAR077 | error | The info object must declare a contact with a non-empty name and email. | | AAR078 | error | The info object must declare a license with a non-empty name and url. | | AAR079 | error | Every External Documentation object must declare a non-empty description and url. | | AAR080 | error | The license name must be an SPDX license identifier, such as Apache-2.0 or MIT, or a LicenseRef- identifier. |

Schema Rules

| Rule | Severity | Description | |------|----------|-------------| | AAR024 | error | Every message must declare a contentType unless it is an Avro message (auto-detected via schemaFormat). | | 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. | | AAR052 | error | The namespace of a named Avro schema (record, enum or fixed) is required and must follow the corporate pattern. | | AAR055 | warn | The x-payload-references extension, wherever it appears, must have subject, ref and referenceName on every item. | | AAR056 | error | When the payload uses Avro, schemaFormat must be application/vnd.apache.avro[+json|+yaml];version=<version> with an allowed version (configurable via allowedVersions; default 1.9.0). | | AAR059 | error | The name field of every Avro record (including nested records) must be in CamelCase with an uppercase first letter. | | AAR060 | error | A message's contentType (and the document-level defaultContentType) must match application/*+avro. | | AAR067 | error | Message and message trait contentType values, and defaultContentType, must be valid MIME types from the allowed list. | | AAR072 | error | Message example payload and headers must be valid against the message schemas. | | AAR074 | warn | Schema property names and Avro field names must follow the configured naming convention (default camelCase); headers are not checked. |


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 55 custom Spectral functions for complex validation logic:

| Function | Used by | Purpose | |----------|---------|---------| | asa-server-protocol-secure | AAR001 | Validates that each root server protocol matches the secure protocol pattern | | 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-operation-id-camel-case | AAR051 | Checks operationId is present and follows camelCase | | asa-message-content-type | AAR024 | Validates each message declares a contentType unless it is Avro | | asa-message-examples-validation | AAR031 | Validates message examples against schemas | | asa-numeric-parameter-integrity | AAR032 | Checks numeric properties have constraints | | asa-numeric-format | AAR034 | Checks numeric properties declare a valid format | | 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 | | asa-avro-namespace-pattern | AAR052 | Validates Avro namespace against the corporate pattern | | asa-channel-naming-convention | AAR053 | Validates channel/topic name against the corporate topic naming pattern | | asa-classification-valid-values | AAR054 | Validates that the channel/topic classification segment is cdc, cmd or sys | | asa-x-payload-references-well-formed | AAR055 | Validates that x-payload-references items each have subject, ref and referenceName | | asa-avro-schema-format | AAR056 | Validates that an Avro schemaFormat declares one of the allowed Avro versions | | asa-error-topic-documented | AAR057 | Validates that at least one channel is documented as an error topic | | asa-retry-topic-naming-convention | AAR058 | Validates that retry channels follow the required retry-topic naming pattern | | asa-avro-record-name-camel-case | AAR059 | Validates that every Avro record's name (including nested records) is in CamelCase | | asa-content-type-avro | AAR060 | Validates that every message contentType and the defaultContentType match application/*+avro | | asa-processor-function-name-paired | AAR061 | Validates that producing and consuming operations share the same x-scs-function-name | | asa-subscribe-group-required | AAR062 | Validates that each consuming operation declares a consumer group | | asa-asyncapi-version-allowed | AAR063 | Validates that the root asyncapi version is one of the allowed versions | | asa-kafka-protocol-required | AAR064 | Validates that each server protocol is kafka or kafka-ssl | | asa-message-format | AAR065 | Checks the casing of message identifiers and names | | asa-tags-format | AAR066 | Checks the casing of tag names | | asa-content-type-values | AAR067 | Validates contentType values against the allowed MIME types | | asa-binding-types | AAR068 | Validates binding keys against the allowed protocols | | asa-binding-required-properties | AAR069 | Checks the required fields of protocol bindings | | asa-binding-version-format | AAR070 | Validates bindingVersion against the configured pattern | | asa-message-examples-required | AAR071 | Checks that every message has a payload example | | asa-message-examples-schema | AAR072 | Validates message examples against their schemas | | asa-message-traits-required | AAR073 | Checks that every message applies a trait | | asa-properties-object-format | AAR074 | Checks the casing of property and Avro field names | | asa-info-attributes-required | AAR075 | Checks the mandatory info fields | | asa-tag-properties-required | AAR076 | Checks the mandatory Tag object fields | | asa-contact-attributes-required | AAR077 | Checks the mandatory info.contact fields | | asa-license-attributes-required | AAR078 | Checks the mandatory info.license fields | | asa-external-docs-attributes-required | AAR079 | Checks the mandatory External Documentation fields | | asa-license-valid-values | AAR080 | Checks the license name against the SPDX License List | | asa-server-name-pattern | AAR081 | Validates server names against the configured pattern | | asa-server-types | AAR082 | Validates server names against the approved server types | | asa-server-host-pattern | AAR083 | Validates server hosts against the configured pattern | | asa-server-protocol-valid-values | AAR084 | Validates server protocols against the allowed transport protocols | | asa-server-protocol-version-valid-values | AAR085 | Validates server protocol versions against the approved versions | | asa-server-attributes-required | AAR086 | Checks the mandatory server fields | | asa-channel-attributes-required | AAR087 | Checks the mandatory channel fields | | asa-channel-servers-required | AAR088 | Checks that every channel lists a root server | | asa-channel-security-valid-values | AAR089 | Validates applied security scheme types against the approved mechanisms | | asa-channel-bindings-required | AAR090 | Checks that every channel declares a kafka binding | | asa-channel-messages-required | AAR091 | Checks that 3.x channel messages include at least one message | | asa-operation-attributes-required | AAR092 | Checks the mandatory operation fields | | asa-operation-bindings-required | AAR093 | Checks that every operation declares a kafka binding | | asa-operation-messages-required | AAR094 | Checks that every operation declares at least one message |


Project Structure

apiaddicts-asyncapi-style-guide-spectral/
├── .github/workflows/       # CI/CD configuration
├── functions/               # Custom Spectral rule functions
│   ├── asa-avro-namespace-pattern.js
│   ├── asa-binding-version.js
│   ├── asa-channel-naming-convention.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
│   ├── asa-content-type-avro.js
│   ├── asa-avro-record-name-camel-case.js
│   ├── asa-error-topic-documented.js
│   ├── asa-avro-schema-format.js
│   ├── asa-string-parameter-integrity.js
│   ├── asa-classification-valid-values.js
│   ├── asa-x-payload-references-well-formed.js
│   └── asa-retry-topic-naming-convention.js
├── test/
│   ├── helpers/
│   │   ├── utils.js            # linterForRule and small shared helpers
│   │   ├── casing.js           # Casing fixtures shared by AAR065, AAR066 and AAR074
│   │   ├── required-fields.js  # Fixtures shared by the required-field rules (AAR075-AAR080, AAR086-AAR088, AAR091, AAR092, AAR094)
│   │   └── rules/              # One fixture module per rule (aarNNN-<name>.js)
│   ├── 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
│       ├── operations/      # Operations rule tests
│       ├── format/          # Format/documentation tests
│       └── schemas/         # Schema rule 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-server-protocol-secure.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 | VULNERABILITY | MAJOR | | AAR033 | asa:AAR033 | VULNERABILITY | MAJOR | | AAR034 | asa:AAR034 | VULNERABILITY | 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 | | AAR050 | asa:AAR050 | BUG | MAJOR | | AAR051 | asa:AAR051 | BUG | MAJOR | | AAR052 | asa:AAR052 | BUG | MAJOR | | AAR053 | asa:AAR053 | BUG | MAJOR | | AAR054 | asa:AAR054 | BUG | MAJOR | | AAR055 | asa:AAR055 | BUG | MAJOR | | AAR056 | asa:AAR056 | BUG | MAJOR | | AAR057 | asa:AAR057 | BUG | MAJOR | | AAR058 | asa:AAR058 | BUG | MINOR | | AAR059 | asa:AAR059 | BUG | MAJOR | | AAR060 | asa:AAR060 | BUG | MAJOR | | AAR061 | asa:AAR061 | BUG | MINOR | | AAR062 | asa:AAR062 | BUG | MAJOR | | AAR063 | asa:AAR063 | BUG | MAJOR | | AAR064 | asa:AAR064 | VULNERABILITY | CRITICAL |

AAR065 and later rules exist only in this Spectral ruleset. ApiQuality registers its style rules (AAR065, AAR066, AAR071, AAR073, AAR074) as CODE_SMELL / MINOR, AAR089 as VULNERABILITY / CRITICAL and the rest as BUG / MAJOR.


Related Projects


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.