Linting a specification

At a glance#

The guidelines are a Spectral ruleset, @api360/spectral-ruleset. It extends the standard spectral:oas rules and adds the rules named on the other pages of this section.

A run exits with 0 when every finding is below the failing severity (warn by default) or covered by the allow-list, and with 1 otherwise.

Run it#

npm install @api360/spectral-ruleset
npx api360-spectral --profile vendor openapi/product.yaml
npx api360-spectral --profile platform --exclude index.json --report-dir spectral-report openapi/domains

The command prints the findings per spec and per rule and writes summary.md, summary.json and findings.json to the report directory. --fail-severity error lets warnings through; --no-allowlist shows everything.

The package comes from the GitLab package registry of the api360-ai group. Point the @api360 scope at it in .npmrc:

@api360:registry=https://gitlab.com/api/v4/projects/84641482/packages/npm/

In a pipeline#

A repository that holds OpenAPI files includes the shared job, which carries the ruleset inside it and needs no registry:

include:
  - project: 'api360-ai/pipeline-orchestrator'
    ref: main
    file: 'ci-templates/spectral-lint.gitlab-ci.yml'
variables:
  SPECTRAL_PROFILE: vendor
  SPECTRAL_PATHS: openapi

The job runs in merge request pipelines, fails on a finding the allow-list does not cover, and keeps the report as an artifact.

The allow-list#

A finding a specification cannot fix yet goes into a dated allow-list, never into a blanket ignore. Each entry names the rule, the reason, the change that closes it, a review date, and a count per specification. One finding above the count fails the run, and an entry past its review date fails it as well, so "clean" means every remaining finding is written down and owned.

Checked by#

See also#

• API design guidelines: the rules as prose.
• For providers: publishing a product.