How can Spectral be used to lint and enforce OpenAPI standards? #

As API programs scale across teams and organizations, maintaining consistency and quality in OpenAPI documents becomes increasingly difficult. Teams may use different naming conventions, omit required fields, or fail to follow security best practices — all without any automated safety net. Spectral, an open-source API linting tool created by Stoplight, addresses this challenge by providing a powerful, extensible ruleset engine that can validate and enforce standards across any OpenAPI document.

What is Spectral? #

Spectral is a command-line tool and JavaScript library that evaluates JSON and YAML documents against a set of rules. While it was purpose-built for OpenAPI, it is format-agnostic and can lint any structured document including AsyncAPI, custom YAML configuration files, and more.

Key capabilities include:

• Built-in OpenAPI ruleset — Spectral ships with opinionated rulesets for OpenAPI 2.0 and 3.x covering best practices, structural correctness, and common mistakes.
• Custom rulesets — teams can write their own rules in JavaScript or use Spectral’s declarative rule syntax to enforce organization-specific standards.
• JSONPath and JSON Pointer targeting — rules target specific nodes in a document using JSONPath expressions.
• Multiple output formats — results can be output as human-readable text, JSON, JUnit XML, or SARIF for integration with code quality platforms.
• CI/CD integration — Spectral can be run as part of any pipeline, making it a natural quality gate for API changes.

Installing Spectral #

Spectral is available as an npm package and can be installed globally or as a project dependency:

npm install -g @stoplight/spectral-cli

For project-scoped installation:

npm install --save-dev @stoplight/spectral-cli

Alternatively, Spectral can be run using Docker:

docker run --rm -it stoplight/spectral lint openapi.yaml

Linting an OpenAPI Document #

Once installed, linting an OpenAPI document is straightforward:

spectral lint openapi.yaml

Spectral will automatically detect whether to apply the OpenAPI 2.0 or 3.x ruleset based on the document’s openapi or swagger field. Results are printed to the console with severity levels: error, warn, info, and hint.

To lint with a specific ruleset file:

spectral lint openapi.yaml --ruleset .spectral.yaml

The Built-in OpenAPI Ruleset #

Spectral’s built-in @stoplight/spectral-openapi ruleset enforces a wide range of quality rules. Examples include:

• operation-operationId — every operation must have a unique operationId.
• operation-summary — every operation must have a non-empty summary.
• operation-tags — every operation should be tagged for proper grouping in documentation.
• openapi-tags — tags used in operations should be declared at the top level.
• info-contact — the info object should include a contact field.
• no-eval-in-markdown — prevents eval() expressions in description fields (a security concern).
• no-script-tags-in-markdown — prevents <script> tags in description fields.
• path-params — every path parameter in a URL template must have a corresponding parameter definition.
• oas3-api-servers — the document should define at least one server.

These rules catch the most common mistakes and omissions in OpenAPI documents before they reach consumers or downstream tools.

Writing a Custom Ruleset #

Custom rulesets allow teams to enforce organization-specific API standards. A Spectral ruleset file (.spectral.yaml) has the following structure:

extends: [[spectral:oas, all]]
rules:
  must-have-x-internal-owner:
    description: All operations must declare an internal owner via x-owner
    severity: error
    given: $.paths.*[get,post,put,patch,delete]
    then:
      field: x-owner
      function: truthy

  operation-summary-max-length:
    description: Operation summaries must be 80 characters or fewer
    severity: warn
    given: $.paths.*[get,post,put,patch,delete].summary
    then:
      function: length
      functionOptions:
        max: 80

Each rule has:

• description — a human-readable explanation of what the rule checks.
• severity — one of error, warn, info, or hint.
• given — a JSONPath expression identifying the nodes to evaluate.
• then — the assertion to apply, using a built-in or custom function.

Built-in Functions #

Spectral provides a set of built-in assertion functions:

The casing function is particularly useful for enforcing naming conventions on operationId, parameter names, and schema property names.

Custom Functions #

For complex assertions, Spectral supports custom JavaScript functions:

rules:
  path-must-include-api-version:
    description: All paths must start with /v{n}/ to include an API version
    severity: error
    given: $.paths
    then:
      function: checkApiVersion

// .spectral/checkApiVersion.js
export default (paths) => {
  for (const path of Object.keys(paths)) {
    if (!/^\/v\d+\//.test(path)) {
      return [{ message: `Path "${path}" must start with /v{n}/` }];
    }
  }
};

Sharing and Extending Rulesets #

Spectral rulesets can be published to npm and extended by other teams:

extends:
  - spectral:oas
  - "@my-org/spectral-ruleset"
rules:
  # override or add rules here

This enables platform teams to publish a central API governance ruleset as an npm package, allowing individual API teams to extend it with project-specific rules while inheriting the organization baseline.

Integrating Spectral into CI/CD Pipelines #

Spectral integrates naturally into CI/CD pipelines. A GitHub Actions example:

name: Lint OpenAPI
on: [push, pull_request]
jobs:
  spectral:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Spectral
        run: npm install -g @stoplight/spectral-cli
      - name: Lint OpenAPI document
        run: spectral lint openapi.yaml --ruleset .spectral.yaml --format junit > spectral-results.xml
      - name: Publish test results
        uses: EnricoMi/publish-unit-test-result-action@v2
        with:
          files: spectral-results.xml

Using the --fail-severity flag, you can control which severity levels cause the pipeline to fail:

spectral lint openapi.yaml --fail-severity error

This allows warnings to pass through without blocking the build while still surfacing them for review.

Spectral in Stoplight Platform #

Stoplight Platform integrates Spectral natively, running linting in real time as designers edit OpenAPI documents in Stoplight Studio. Rule violations appear inline in the editor, making it easy to catch and fix issues during authoring rather than at CI time.

Conclusion #

Spectral is the de facto standard for OpenAPI linting and style enforcement. Whether enforcing the built-in OpenAPI ruleset, writing organization-specific custom rules, or publishing shared rulesets across an API program, Spectral provides the tooling needed to maintain consistent, high-quality API descriptions at scale. Integrating Spectral into CI/CD pipelines ensures that every API change is validated before it reaches consumers, making it an essential part of any mature API governance workflow.

Last updated on April 29, 2026.