@luxass/spectral-ruleset

Opinionated ruleset for Spectral with focus on best practices for OpenAPI and AsyncAPI specifications.

[!IMPORTANT] This package provides a collection of rules that enforce API best practices and conventions. The rules are designed to help you create more consistent and maintainable API specifications.

Installation

npm install @luxass/spectral-ruleset

Usage

Create a .spectral.yml file:

extends:
  - "@luxass/spectral-ruleset"

Or quickly create one using:

echo 'extends: ["@luxass/spectral-ruleset"]' > .spectral.yml

You can also use it directly from unpkg:

echo 'extends: ["https://unpkg.com/@luxass/spectral-ruleset"]' > .spectral.yml

Rules

This ruleset extends the official OpenAPI and AsyncAPI rulesets from @stoplight/spectral-rulesets, with some built-in rules modified (operation-tags and operation-operationId are disabled, operation-success-response is set to error level).

Custom Rules

General Rules

luxass/api-homepage ⚠️

Ensures that APIs have a root path (/) defined. This helps with API discoverability and provides a clear entry point for consumers.

luxass/api-homepage-get ⚠️

Ensures that the API root path (/) has a GET operation defined. This allows consumers to discover what the API offers.

luxass/version-in-info ⚠️

Enforces semantic versioning format for the info.version field (e.g., 1.0.0).

Path Rules

luxass/paths-kebab-case ⚠️

Enforces kebab-case naming convention for all API paths (e.g., /user-profiles instead of /userProfiles).

luxass/no-file-extensions-in-paths ❌

Prevents file extensions (.json, .xml, .html, .txt) in API paths. Use the content field to specify media types instead.

luxass/no-trailing-slash ⚠️

Prevents trailing slashes in paths (except for the root path /), avoiding confusion about resource identity.

luxass/plural-resource-names ⚠️

Encourages using plural nouns for resource collections (e.g., /users instead of /user).

Header Rules

luxass/no-x-headers ❌

Prevents usage of headers starting with X- prefix. Encourages using standardized headers instead of the deprecated X- convention.

luxass/headers-hyphenated-pascal-case ❌

Enforces Hyphenated-Pascal-Case notation for HTTP headers (e.g., Content-Type, Accept-Language).

OpenAPI 2.0 Specific Rules

luxass/oas2/protocol-https-only ❌

Ensures that only HTTPS protocol is used in the schemes array.

luxass/oas2/get-request-no-body ❌

Prevents GET requests from having request bodies, following HTTP best practices.

OpenAPI 3.x Specific Rules

luxass/oas3/protocol-https-only ❌

Ensures that all server URLs use HTTPS protocol only.

luxass/oas3/get-request-no-body ❌

Prevents GET requests from having requestBody defined, following HTTP best practices.

📄 License

Published under MIT License.