What is OpenAPI linting?

OpenAPI linting is the automated checking of an OpenAPI or Swagger document against a set of rules, usually covering naming conventions, required metadata, security declarations, and whether examples validate against their own schemas. It is the machine-enforced form of an API style guide, and it runs on the document alone.

What should an API style guide enforce?

At minimum: an owner and contact, HTTPS servers, consistent path and operation naming, declared error responses including the 401 and 403 that any authenticated operation implies, and examples that validate against their schemas. Beyond the document, a mature style guide also asks whether an operation is claimed by a requirement, whether any run has ever exercised it, and whether anything other than a mock has answered it.

Can I keep using Spectral?

Yes. Spectral is a good document linter and it is free. Karate is designed to sit above it rather than replace it: ingesting your existing Spectral or vacuum findings as evidence, and converting your rulesets onto an engine whose rules can also read your coverage graph and contract-test results. Ruleset ingest and conversion ship this quarter. The graded evidence join is available today.

Is the lint deterministic?

Yes. There is no model and no network call involved. The same document and the same rulepack produce the same findings every time, and a rule whose selector cannot pin an exact position reports nothing rather than guessing at one.

OpenAPI Linting

OpenAPI linting,
plus the evidence
behind it.

Q: Is OpenAPI linting enough to say an API is well governed?

No. A ruleset can only ask questions the document can answer about itself. A perfectly linted document can describe operations that no requirement claims, that no test has ever called, and that only your own mock has ever answered. Linting establishes that an API is well described. Governance requires evidence that it is exercised.

Your style guide catches naming and structure. It cannot tell you that this operation is required by nobody, has never been called, and has only ever been answered by your own mock.

See the rulepack Compare with Spectral

what a finding looks like

error security-scheme-declared

No security scheme is declared anywhere, so nothing downstream can tell an intentionally public API from an undescribed one.

document root · line 1

warn server-https

Server url 'http://localhost:8080' is not https.

/servers/0 · line 12

evidence operation-not-mock-only

Operation 'createQuote' has only ever been answered by a karate mock. Its green is mock-only.

/paths/~1quotes/post · line 26 · from the coverage graph

The Rulepack

The rules you expect, plus three you can't get elsewhere

Document rules

✓Owner and contact declared
✓Servers use HTTPS
✓Consistent path and operation naming
✓Error responses declared, including the ones auth implies
✓Examples validate against their own schema

Evidence rules

→Is this operation claimed by a requirement
→Was it ever exercised by a run
→Did anything other than our own mock answer it

These read your coverage graph and your contract-test results, not the document. No ruleset can ask them of a file.

Exact positions

Severity, message, JSON pointer, and line. A rule that cannot pin a position reports nothing rather than guessing.

Deterministic

No model, no network. Same document plus same rulepack gives the same findings, every time.

Not gameable

Declaring a security scheme raises the obligations that come with it. You cannot lint your way to a good grade.

Real Output

40 findings against our own spec

This is the reference kit's openapi.yaml, graded against 31 rules. We publish it whether it looks good or not.

1 error 19 warnings 20 info findings 1 dimension not measured

Severity	Rule	Message	Position
error	`security-scheme-declared`	No security scheme is declared anywhere	root · line 1
warn	`info-contact`	Nobody is named as the owner of this API	/info · line 3
warn	`server-https`	Server url is not https	/servers/0 · line 12
warn	`operation-error-response`	Operation declares no 4xx or 5xx response, so its error contract is undocumented	/paths/~1policies/get · line 53
warn	`operation-claimed-by-requirement`	No requirement claims operation createQuote. It is an orphan in the traceability graph	/paths/~1quotes/post · line 26
warn	`operation-exercised`	Operation cancelPolicy was never exercised by any test	/paths/~1policies~1{id}/delete · line 97
info	`operation-not-mock-only`	Operation createQuote has only ever been answered by a karate mock. Its green is mock-only	/paths/~1quotes/post · line 26

Rows 1 to 4

Ordinary style-guide findings. Any good document linter will produce these, and you should already have a tool that does.

The tinted rows

These three are not in the document at all. They come from the coverage graph and the contract results, and no ruleset can derive them from a file.

See all 40 findings in the live report

The Upgrade Path

This is not a replacement for your style guide

It is the layer above it. Keep the rules you have and grade what they cannot see.

A ruleset can only ever ask questions the document can answer. That is a ceiling, not a defect. A perfectly linted document can still describe operations that no requirement claims, that no test has ever called, and that only your own mock has ever answered, and every rule will pass.

Keep the linting you have. Grade the evidence behind it.

Bringing rules across

Spectral and vacuum findings can be ingested as evidence, and existing rulesets converted onto an engine whose rules can also read your coverage graph. Ruleset ingest and conversion ship this quarter. The graded evidence join is available today.

OpenAPI linting,plus the evidencebehind it.