Providing an index of the machine-readable rules available for governing APIs, offering rules for linting API operations, as well as the surface area of each API, helping standardize how APIs are design, but also delivered across teams within an enterprise.

Also known as: Linting Rules, Style Rules, Governance Rules, Rulesets

Example

- type: SpectralRules
  url: https://developers.example.com/.spectral.yaml
  mediaType: application/yaml

Standards

• OpenAPI Initiative OpenAPI Specification 3.1
• AsyncAPI Initiative AsyncAPI Specification
• JSON Schema JSON Schema 2020-12
• IETF RFC 9535 — JSONPath
• Stoplight Spectral built-in ruleset — spectral:oas
• Stoplight Spectral built-in ruleset — spectral:asyncapi
• Stoplight Spectral custom rulesets

Media Types

• application/yaml — Spectral, Redocly, and Vacuum rulesets are typically authored as YAML.
• application/json — Rulesets and JSON Schema documents.
• text/x-javascript — Spectral custom functions and rulesets authored as ES modules.

OpenAPI Expression

• x-spectral-ruleset (Vendor extension (de facto)) — Points to a Spectral ruleset that governs the API description.
• info.x-api-governance (Vendor extension) — Custom marker linking a description to its governance ruleset.

Governance Rules

• oas3-api-servers (Spectral built-in (spectral:oas)) — OpenAPI 3.x descriptions must define a servers array.
• operation-operationId (Spectral built-in (spectral:oas)) — Every operation must have an operationId.
• operation-tag-defined (Spectral built-in (spectral:oas)) — Operation tags must be defined in the global tags array.
• no-$ref-siblings (Spectral built-in (spectral:oas)) — $ref must not have sibling properties (OAS 3.0).
• info-contact (Spectral built-in (spectral:oas)) — info.contact is required so consumers can reach the producer.

Risk & Compliance

Security: Weak or absent linting rules let security-sensitive defects (missing security schemes, undefined responses, leaked debug servers) ship to production. Pair lint rules with CI gates and treat rule changes as audited governance artifacts.

Tools

• Spectral — Linter (Apache-2.0)
• Vacuum — Linter (Go, Spectral-compatible) (MIT)
• Optic — API diff and governance
• Redocly CLI lint — Linter
• AJV — JSON Schema validator (MIT)
• JSONPath Plus — JSONPath engine (Spectral default) (MIT)

Suggested Metrics

• rule_violation_count — Number of rule violations per lint run, broken down by severity.
• lint_pass_rate — Share of CI runs whose API description passes the active ruleset without errors.
• ruleset_version_drift — Number of repositories pinned to an outdated central ruleset.
• time_to_fix_violation_p50 — Median time between a rule violation being reported and its resolution.

Example Implementations

• Stoplight — Reference implementation of Spectral and the spectral:oas / spectral:asyncapi rulesets.
• Redocly — Redocly CLI lint with configurable OpenAPI rules and decorators.
• Postman — API governance rules surfaced inside the Postman API platform.

Related Properties

• Policies
• Openapi
• Asyncapi
• Schema
• Tests
• Governance

Tags

• Rules
• Spectral
• Governance
• Technical
• Engineering
• Linting

All Common Properties