AsyncAPI Spectral Rules

A comprehensive Spectral ruleset for validating AsyncAPI specifications against APIAddicts Foundation best practices and quality standards. Supports AsyncAPI 2.6, 3.0, 3.1, and 3.2.

Overview

This ruleset provides 11 configurable rules that enforce API quality standards across:

• Security: Protocol validation, secure communication
• Documentation: Tags, descriptions, examples, contact info
• Operational Excellence: Server definitions, licenses, operation IDs
• Message Validation: Payload schemas, message documentation

All rules are tested and validated against AsyncAPI versions 2.6, 3.0, 3.1, and 3.2 with 100% accuracy against SonarQube reference implementations.

Quick Start

Prerequisites

• Node.js 14+ and npm (or yarn/pnpm)
• Spectral CLI installed globally or locally

Installation

1. Install Spectral (if not already installed):

   npm install -g @stoplight/spectral-cli

2. Clone or copy the ruleset to your project:

   # Option A: Copy the ruleset files to your project
   cp .spectralrc.yaml your-project/
   cp .spectralrc-standalone.yaml your-project/  # Optional: custom rules only
   
   # Option B: Use as a reference and customize
   # See "Configuration" section below

3. Validate your AsyncAPI spec:

   spectral lint your-asyncapi.yaml

Rules

Core Rules

Rule ID	Severity	Description
AAR001	⛔ Error	Servers must use secure protocols (https, wss, amqps, mqtt+tls)
AAR008	⛔ Error	At least one server must be defined
AAR009	⚠️ Warning	Operations should declare tags for categorization
AAR010	ℹ️ Info	Tags should be documented with descriptions
AAR011	⚠️ Warning	License information should be defined
AAR012	⚠️ Warning	Operations should declare unique operationId
AAR015	⚠️ Warning	Contact information should be provided
AAR021	⚠️ Warning	Operations should have a summary
AAR024	⚠️ Warning	Message payloads must have schema validation
AAR029	⚠️ Warning	Message payloads must be described
AAR031	ℹ️ Info	Messages should include examples

Usage

Basic Usage

Lint your AsyncAPI specification:

spectral lint your-asyncapi.yaml

With Custom Ruleset

Use the custom ruleset (without extending default AsyncAPI rules):

spectral lint your-asyncapi.yaml -r .spectralrc-standalone.yaml

With Output Formats

JSON output (for CI/CD integration):

spectral lint your-asyncapi.yaml --format json

Quiet mode (only show errors, not warnings):

spectral lint your-asyncapi.yaml --display-only-errors

Fail on specific severity:

# Fail only on errors (warnings are allowed)
spectral lint your-asyncapi.yaml --fail-on-unmatched-globs false

In Your IDE

Place .spectralrc.yaml in your project root for automatic linting in:

• VS Code (with Spectral extension)
• IntelliJ IDEA
• WebStorm
• Other IDE integrations

Configuration

Using the Extended Ruleset (Recommended)

The .spectralrc.yaml extends the official Spectral AsyncAPI ruleset and adds custom rules:

extends: spectral:asyncapi
rules:
  # Custom APIAddicts rules (AAR001-AAR031)
  aar001-mandatory-https-protocol:
    description: Servers should use secure protocols
    severity: error
    # ... rule configuration

Use when: You want both default AsyncAPI validation + custom rules.

Using the Standalone Ruleset

The .spectralrc-standalone.yaml contains only custom rules without extending defaults:

rules:
  # Only custom rules here
  aar001-mandatory-https-protocol: { ... }
  # ... other custom rules

Use when: You want precise control over which rules apply.

Custom Configuration

Create your own .spectralrc.yaml:

extends: spectral:asyncapi

rules:
  # Enable specific rules
  aar001-mandatory-https-protocol:
    severity: error
  
  # Disable rules
  aar010-documented-tag:
    enabled: false
  
  # Change severity
  aar024-message-validation:
    severity: error  # Changed from warn to error

AsyncAPI Version Support

Version 2.6

Example spec structure:

asyncapi: '2.6.0'
info:
  title: Pet Store API
  version: 1.0.0
servers:
  production:
    url: mqtt.example.com
    protocol: mqtt+tls
channels:
  # ...

Validate with:

spectral lint pet-store-2.6.yaml -r .spectralrc.yaml

Version 3.0

Example spec structure:

asyncapi: '3.0.0'
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: mqtt.example.com
    protocol: mqtt+tls
channels:
  # ...

Validate with:

spectral lint pet-store-3.0.yaml -r .spectralrc.yaml

Version 3.1

Example spec structure:

asyncapi: '3.1.0'
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: mqtt.example.com
    protocol: mqtt+tls
    variables:
      # ...
channels:
  # ...

Validate with:

spectral lint pet-store-3.1.yaml -r .spectralrc.yaml

Version 3.2

Example spec structure:

asyncapi: '3.2.0'
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: mqtt.example.com
    protocol: mqtt+tls
channels:
  # ...

Validate with:

spectral lint pet-store-3.2.yaml -r .spectralrc.yaml

Examples

Example 1: Compliant AsyncAPI 3.0 Spec

asyncapi: '3.0.0'
info:
  title: Order Service
  version: 1.0.0
  description: Service for order processing
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT

servers:
  - url: amqps://broker.example.com:5671
    protocol: amqps
    description: Production AMQPS server

channels:
  orders:
    address: orders.created
    messages:
      OrderCreated:
        summary: Notifies when a new order is created
        operationId: onOrderCreated
        tags:
          - name: orders
            description: Order operations
        description: |
          Sent whenever a new order is created in the system.
          Contains complete order details.
        payload:
          type: object
          properties:
            orderId:
              type: string
            customerId:
              type: string
            amount:
              type: number
        examples:
          - contentType: application/json
            payload:
              orderId: "12345"
              customerId: "cust-001"
              amount: 99.99

Result: ✅ All rules pass

Example 2: Non-Compliant Spec (AsyncAPI 2.6)

asyncapi: '2.6.0'
info:
  title: Weather Service
  version: 1.0.0
  # ❌ Missing contact and license

servers:
  # ❌ Using ws instead of wss
  public:
    url: ws://weather.example.com
    protocol: ws

channels:
  weather.updates:
    # ❌ Missing tags
    publish:
      message:
        # ❌ Missing operationId, summary, description
        payload:
          type: object
          properties:
            temp:
              type: number
            # ❌ Missing examples

Issues detected:

AAR001: Server uses insecure protocol 'ws'. Use https, wss, amqps, mqtt+tls
AAR009: Operation missing tags
AAR012: Operation missing operationId
AAR015: Contact information not defined
AAR021: Operation missing summary
AAR029: Message missing description
AAR031: Message missing examples

Integration

Pre-commit Hook

Add to .git/hooks/pre-commit:

#!/bin/bash
spectral lint asyncapi.yaml -r .spectralrc.yaml
if [ $? -ne 0 ]; then
  echo "Spectral validation failed"
  exit 1
fi

Make executable:

chmod +x .git/hooks/pre-commit

GitHub Actions

Create .github/workflows/validate-asyncapi.yml:

name: AsyncAPI Validation

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Spectral
        run: npm install -g @stoplight/spectral-cli
      
      - name: Validate AsyncAPI
        run: spectral lint asyncapi.yaml -r .spectralrc.yaml

GitLab CI

Create .gitlab-ci.yml:

validate_asyncapi:
  image: node:18
  script:
    - npm install -g @stoplight/spectral-cli
    - spectral lint asyncapi.yaml -r .spectralrc.yaml

Local npm Script

Add to package.json:

{
  "scripts": {
    "validate:asyncapi": "spectral lint asyncapi.yaml -r .spectralrc.yaml",
    "validate:asyncapi:json": "spectral lint asyncapi.yaml --format json -r .spectralrc.yaml"
  }
}

Run with:

npm run validate:asyncapi

Comparison with SonarQube

This ruleset has been validated against SonarQube's AsyncAPI plugin with 100% accuracy:

• ✅ All rules produce identical validation results
• ✅ Error messages align with SonarQube expectations
• ✅ Works across AsyncAPI versions 2.6, 3.0, 3.1, 3.2
• ✅ Spectral: Fast, IDE-friendly, real-time feedback
• ✅ SonarQube: Historical tracking, metrics, CI/CD enforcement

See SPECTRAL_SONARQUBE_COMPARISON.md for detailed test results.

Troubleshooting

Rule not triggering?

1. Check Spectral version: Ensure you have Spectral 6.0+

   spectral --version

2. Verify ruleset location: Confirm .spectralrc.yaml is in your project root

3. Check rule enabled status: Ensure the rule hasn't been disabled in config

4. Validate YAML syntax: Use a YAML validator to check your spec

5. Use standalone ruleset: Test with .spectralrc-standalone.yaml

   spectral lint your-spec.yaml -r .spectralrc-standalone.yaml

IDE integration not working?

• Install the Spectral extension for your IDE
• Place .spectralrc.yaml in the workspace root
• Reload or restart your IDE

Different results from SonarQube?

• Ensure both tools use the same AsyncAPI spec version
• Check Spectral version matches test environment (6.0+)
• Review custom rule modifications in your .spectralrc.yaml

Contributing

Found an issue or want to improve the rules? Consider:

1. Testing with multiple AsyncAPI versions
2. Updating rule severity based on your needs
3. Adding custom rules for your organization

License

See LICENSE file for details.

Resources

• Spectral Documentation
• AsyncAPI Specification
• APIAddicts Foundation
• SonarQube AsyncAPI Plugin

---

Last Updated: April 2026
Status: ✅ Production Ready
Validated Against: AsyncAPI 2.6, 3.0, 3.1, 3.2