Linting takes a ruleset and evaluates it against a machine-readable definition — an OpenAPI, an AsyncAPI, a JSON Schema — reporting where the document violates your standards. It is what turns “we should name paths in kebab-case” into an automated check that runs in the editor, the CLI and the pipeline.
A sensible progression to lint for:
Structural first — is the document valid against the specification, does it parse, do all references resolve. Then completeness — every operation has a summary and description, every response is documented including errors, every schema has types and examples. Then security — every API declares a security scheme, no operation is unintentionally unauthenticated, no schema accepts unbounded input. Then consistency — casing, path structure, naming, error format, versioning, date formats. Then organization-specific rules, which are where the real value is and where you should end up rather than start.
Two cautions. Rules are a start, not the thing itself — a rule is only ever a representation of something that matters, and a portfolio can pass every lint while still being incoherent. And when I measured a thousand real public pipelines, most teams had turned on a linter with its factory-default ruleset and stopped, treating the green check as governance. That is the most common failure mode, and it looks exactly like success from the outside.
