API consistency keeps interface, behavior, and design conventions coherent across API products. As delivery scales, inconsistency appears alongside long design lead times and documentation problems, making consistency an APIOps improvement target. section 2.14 section 3.0
Apply consistency rules to existing APIs using one of three organizational strategies:
- Big-bang consistency applies the complete ruleset and updates the API design and code, but may require disruptive or breaking changes. section 3.9
- Multi-ruleset consistency gives each project a passing ruleset, enabling minimal compliance for extensions while duplicating rules and leaving gaps. section 3.9
- Gradual consistency retains one ruleset, selectively disabling or lowering failing rules for specific OpenAPI objects while enforcing standards on new changes. section 3.9
Override a rule for an existing operation
A Spectral ruleset can require operationId values globally, then override that rule for a legacy PUT operation and downgrade it to a warning for DELETE. Running `$ spectral lint openapi.yaml --ruleset ruleset2.yaml` reports the remaining violation as a warning, allowing modernization without blocking delivery.
Automated linting catches repeatable consistency and usability problems, but early design engagement and review remain necessary for issues automation cannot judge. section 5.3.3 section 10.0
