Chapter 07 of 10
Validating and Linting OpenAPI
Validation answers whether a document is legal OpenAPI and linting answers whether it is any good. What each one catches, which rules find real defects, and how severities decide what blocks a release.
Two different questions get asked of the same file, and running one and calling it the other is how a document ends up technically valid and unusable.
Validation answers one question
A validator compares your document against the specification and tells you whether it is legal. That question has a correct answer, so two validators should agree.
What it catches is worth knowing, because it is narrower than people assume. It finds a missing required field such as a response description, and it finds a path template containing {orderId} with no matching parameter declaration. It finds a $ref pointing at a component that does not exist, and it finds a keyword the declared version does not support, which is what happens when a 3.0 document uses const or prefixItems.
What it does not catch is everything about quality. A document where every response is an untyped object, no operation has a description and no error is documented passes validation without a word.
Linting answers the other one
A linter checks the document against conventions rather than against the specification, so the rules are yours and there is no universal correct answer.
The useful rules fall into five groups, and most tools organise them roughly this way.
Naming. Path segments, path and query parameter names, schema names, property names, enum values and operation identifiers each follow one convention. The value is not tidiness, it is that a reader can predict the next name, and a generator produces types that look like the rest of the codebase.
Completeness. Operations have a summary and a description, parameters and schemas have descriptions, the document has a server URL and a version. These are the rules that decide whether generated documentation is readable.
Best practice. Operation identifiers are unique, declared path parameters match the template, two paths do not collide, list endpoints have pagination parameters, endpoints declare at least one error response.
Security. The server URL uses HTTPS, an API key is not carried in a query parameter, endpoints reference a security scheme, and schema properties do not look like passwords or card numbers.
Structure. Arrays define their items, enum values match the declared type, no response that forbids a body declares one, and examples validate against their schemas.
The rules that are worth an error
The distinction that matters is between a rule about taste and a rule about something breaking downstream.
Five examples of the second kind, each of which produces a real defect rather than an inconsistency.
Duplicate operation identifiers. Generators use them as method names, so a duplicate produces a client that does not compile or one that silently loses a method.
Two paths that are the same route. OpenAPI ignores the name of a path placeholder, so /items/{id} and /items/{itemId} are one path declared twice, and the second declaration is unreachable.
An array without an items schema. Every generator produces an untyped list, and every mock returns an empty one.
An example that contradicts its schema. Readers trust examples more than schemas, so a stale example is worse than no example.
A body on a 204 or a 304. RFC 9110 forbids a message body on those statuses, so a document that declares one makes generators emit deserialisation code that will never run.
Everything else is real and belongs at warning, where it gets reported and fixed without stopping a release that is otherwise fine.
Severities are the policy
Rules are only half a style guide, and the severity assigned to each one is the other half.
Error should mean that the release stops, warning should mean that somebody reads it, and info should mean that it is a hint worth having. A style guide where everything is an error stops being read within a month, because the only way to ship is to ignore it. Once people ignore the noisy rules, they stop seeing the important ones.
That is also why enforcement belongs at the publishing step rather than at every save. Checking as you type is helpful, and blocking as you type is how people learn to work around the tool.
Where linting fits in a release
A style guide that runs on somebody's laptop is a suggestion, while the same rules running before a merge and before a publish are a contract.
The practical arrangement has two points. The rules run continuously while somebody edits, so violations are fixed where they were made, and they run again when a version is released, where error-level violations stop it. Anything between those two points is optional.
In Routebase
Validation and linting are separate in the product for the same reason they are separate in this chapter. An imported file is validated against the specification, with the errors listed above an editor so the file can be fixed in place, and the style guide runs continuously against the specification you are editing.
The built-in rules cover the five categories above, and each one has a severity you can change for the organisation and override per project. Where a rule enforces a naming convention the convention itself is a setting, so a team that has always written /userProfiles keeps the check instead of turning it off. Custom rules add checks of your own on a target, a field and a condition.
Violations surface in an issues panel in the designer with per-severity filters, on the tree next to the endpoint that caused them, and in the publish dialog. With enforcement on, error-level violations block the release, and warnings can be published after a confirmation. The Style Guide guide covers the rules, the severities and the quality score built on them. How the same rules become a standard that several teams share is the subject of the API governance guide.
Frequently asked questions
What is an OpenAPI validator?
A validator checks a document against the specification and answers one question, which is whether the file is legal OpenAPI. It catches a missing required field, a path parameter that is declared nowhere, a reference that points at something absent and a keyword the declared version does not have. A document can pass validation and still be almost useless to a reader.
What is the difference between validating and linting an OpenAPI file?
Validation is objective and linting is a matter of policy. A validator has one correct answer because the specification defines it, while a linter checks the conventions your team chose, such as naming, required descriptions and a consistent error shape. Both are worth running, and only the first one has a right answer everybody agrees on.
Which OpenAPI lint rules actually catch bugs?
The ones that describe something a machine downstream will get wrong. Duplicate operation identifiers break generated clients, and two paths that differ only in the name of a placeholder are the same route. An array without an items schema produces an untyped list, an example that contradicts its schema misleads every reader, and a body on a 204 makes generators emit dead code.
Should lint errors block a release?
Some of them, and the way to decide is to ask what happens downstream if the rule is violated. A rule whose violation produces broken generated code belongs at error severity and should block. A rule about naming style is real and should not stop a release on its own, so warning is the honest level for it.
Last reviewed by The Routebase Team.