13 / Rules with reasons
Make API design rules visible before review becomes an argument
Lint OpenAPI descriptions for structural problems and team conventions, with findings that point to the affected part of the contract.
18 /users/{id}:19 get:20 operationId: getUser21 responses:HS-204Document the 404 responseline 21
Working reference
What goes in, what comes out, and what the result can prove.
Concrete artifact
A lint rule should explain the design consequence
WARN paths./orders.get.responses
Rule operation-success-response
Why operation has no explicit 2xx response
Fix document the success status and schemaReview sequence
Three checks before the result becomes a decision.
Parse first
Report syntax failures separately from design rules.
Locate
Attach the rule to a JSON Pointer or source position.
Explain
Give rationale and a concrete repair, not only a rule ID.
Limits
What this workflow does not prove.
- Lint rules encode conventions; they do not prove runtime correctness.
- Organization-specific exceptions should be documented, not silently disabled.
- A clean specification can still describe a poorly behaved API.
Questions worth answering
Before you put it into a real workflow.
Does linting replace contract testing?
No. Linting reviews the description; contract testing compares documented behavior with changes or execution.
Can teams use custom rules?
Team and workspace capabilities can apply a selected ruleset or policy baseline.
Can linting run before a pull request merges?
Yes. Use the automation or API surface to place lint checks in CI.
Next move
Start with one concrete API problem.
Keep the first step small. Move into a workspace when the result deserves to be saved, repeated, or shared.