@apiaddicts/asyncapi-style-guide-spectral
v2.1.1
Published
Spectral ruleset for AsyncAPI definitions by APIAddicts / ApiQuality
Maintainers
Readme
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/asyncapi-style-guide-spectral.git
cd apiaddicts-asyncapi-style-guide-spectral
npm installUsage
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.yamlSpectral Config File
Create a .spectral.yaml in your project root:
extends:
- https://raw.githubusercontent.com/apiaddicts/asyncapi-style-guide-spectral/main/asa-spectral.yamlThen run:
spectral lint your-asyncapi.yamlVSCode Extension
- Install the Spectral VSCode extension.
- Create a
.spectral.yamlfile as shown above. - 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.mdRunning Tests
# Run all tests with coverage
npm test
# Run a specific test file
npx jest test/asyncapi2/security/aar001-server-protocol-secure.test.jsMapping 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
- 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.
