lint

Elastic OpenAPI Linter

Lint an OpenAPI 2.0 (Swagger), 3.0, or 3.1 spec against the centralized Elastic ruleset (Spectral)

Inputs

Name	Description	Required	Default
spec-path	Repo-relative path to the OpenAPI spec file (JSON or YAML)	true
fail-on-warn	Fail the check on warning-level convention issues, not just errors	false	false

Outputs

Name	Description
error-count	Number of error-level results
warning-count	Number of warning-level results
results-file	Path to the machine-readable JSON results file

Usage

steps:
  - uses: actions/checkout@v6
    with:
      persist-credentials: false
  - uses: elastic/docs-actions/openapi/lint@v1
    with:
      spec-path: docs/openapi/api.yaml

Ruleset

The ruleset is centralized in this action (openapi/lint/ruleset.yaml) — consumers do not author their own rules. Rule changes are proposed via PR to elastic/docs-actions.

It has two severity tiers:

• error — the spec parses, all $refs resolve, and it conforms to the OAS schema for its detected version (Swagger 2.0, OpenAPI 3.0.x, or OpenAPI 3.1.x). These always fail the check.
• warn — authoring conventions, currently the generic hygiene rules built into spectral:oas (operationId presence, required descriptions/tags/servers, tags defined at root). These pass by default so existing specs aren't broken; set fail-on-warn: true to enforce them.

Elastic-specific conventions (operationId casing, security scheme naming, the x-state shape) aren't encoded as rules yet — they're sketched as commented-out examples in ruleset.yaml pending team agreement (see the analysis in elastic/docs-eng-team#639). Land them via PR once adopted.

spec-path should be repo-relative — PR annotations are anchored to the path as given, so an absolute path won't map back to a file in the diff.

This action installs Spectral via npm ci against a lockfile committed in this directory (openapi/lint/package-lock.json), pinning the full dependency tree — not just the CLI version — so lint results are reproducible run to run. It only calls the public npm registry and needs no secrets, so it's safe to run on fork PRs.

Note: an allowlist rule for x-* vendor extensions is planned as a follow-up and is not yet part of this ruleset.