spectral "lint errors" on openapi document, operation missing

TL;DR

Add the missing field the rule demands - usually a unique operationId on each operation - then rerun the linter until it reports no errors. Spectral's default OpenAPI ruleset requires operation IDs because code generators and doc tools key off them. If a rule does not fit your API, demote it to a warning in your ruleset instead of ignoring the lint output.

The error

"lint errors" on openapi document, operation missing

Steps

1. Run the linter: npx @stoplight/spectral-cli lint openapi.yaml. Expected: a list of violations, each with a file, line number, rule name, and message.
2. For each operation flagged as missing an ID, open the operation and add a unique operationId, for example listWidgets for GET /widgets. Expected: every operation in the spec has an operationId.
3. For other errors (missing info.description, unused components, and similar), fix each as the message describes. Expected: you can explain what each remaining violation asks for.
4. Rerun the linter. Expected: it reports no results with a severity of error or higher.
5. If your pipeline treats warnings as failures too, open .spectral.yaml and set rules that do not apply to your API to warn or off, documenting why. Expected: the ruleset file reflects a deliberate choice per rule.

Use this when

• spectral lint exits nonzero on an OpenAPI document.
• CI blocks docs generation or publishing on lint errors.
• Operations are flagged as missing operationId or similar required fields.

Not for this skill when

• The failure is a Spectral crash or ruleset-load error rather than lint findings.
• You need to write a custom Spectral rule from scratch - that is ruleset authoring, not fixing findings.
• The spec fails in a different validator with no Spectral involvement.

Variant phrasings

spectral found errors in openapi spec

Same tool, same fix loop: run, read the rule messages, fix, rerun.

operation must have operationId

This is the single most common Spectral finding on OpenAPI 3 specs. Same fix.

openapi lint failed in CI

CI usually runs the linter with a fail-on-error severity. Reproduce locally with the same command and flags before pushing fixes.

Why it happens

Spectral applies a ruleset of best practices to the spec, and several rules exist because downstream tools assume them: operationId feeds codegen method names and doc anchors, info fields feed rendered headers. Specs written by hand or merged from multiple sources routinely skip these fields, so the first lint run on a mature spec often surfaces a backlog.

Edge cases

• Duplicate operationId values: the rule requires uniqueness too. A copy-pasted operation with the same ID fails the same rule a second time.
• Ruleset extension chains: if your ruleset extends another, a rule you turned off can come back via the parent. Check the resolved ruleset, not just your file.
• Spectral versions change rule names and severities. Pin the CLI version in CI so local and remote runs agree.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst2w1wm--t7edz76cruHUHQ