You test for breaking changes. You enforce deprecation timelines. You plan version rollouts. But the specification itself — the document that defines what every contract test, schema evolution, and version rollout is about — nobody validates that.
A missing parameter description. An undocumented error response. A schema that says type: object with no properties defined. These aren't breaking changes. They don't trigger contract tests. They don't violate deprecation policies. They just silently degrade every downstream system that trusts the spec to be complete.
This is the foundation gap. Every API lifecycle tool — contract testing, schema evolution, version routing — assumes the specification is correct, complete, and well-documented. When it isn't, the tools work perfectly on bad data.
The Three API Specification Primitives
1. OpenAPI Linter ($0.001/call)
Lint OpenAPI 3.x and Swagger 2.0 specifications against configurable rulesets:
- Spectral-compatible rules: Built-in rulesets covering OAS best practices, naming conventions, security definitions, pagination patterns, and error response consistency — plus custom rule definitions
- CI-gate verdicts: Pass/warn/fail verdicts with per-rule severity overrides and path-level exemptions
- Auto-fix suggestions: Where applicable, machine-applicable patches that resolve findings without manual editing
- Incremental linting: Baseline comparison that surfaces only new violations in PRs, not every historical issue
One team ran their 340-endpoint specification through the linter and found 47 undocumented error responses, 12 missing parameter descriptions, and 8 inconsistent naming conventions. None of these would trigger a breaking change detector. All of them were degrading the developer experience for every consumer.
2. API Documentation Quality Scorer ($0.002/call)
Score API documentation completeness across six measurable dimensions:
- Description coverage: Every path, parameter, and schema has a meaningful description — not just a name
- Example quality: Request/response examples that actually validate against the schema
- Schema completeness: All response shapes fully typed with no bare objects or
anytypes - Error documentation: Every non-2xx status code documented with error schema and resolution steps
- Authentication documentation: Auth flows, scopes, and token lifecycle explained
- Pagination documentation: Collection endpoints document their pagination strategy, filter parameters, and sort options
Returns per-dimension scores (0–100), an aggregate letter grade (A+ through F), and prioritized improvement suggestions with estimated effort. Run it on version bumps to track whether documentation quality is improving or regressing.
3. Spec Diff Visualizer ($0.002/call)
Generate human-readable visual diffs between specification versions:
- Structural change categorization: Changes classified as additions, removals, modifications, deprecations, and renames — not line-by-line text diffs
- Consumer impact assessment: Each change assessed as breaking, non-breaking, or informational
- Security-relevant highlighting: Auth scope changes, new required headers, and TLS requirement modifications flagged with special markers
- Multi-format output: Markdown for PR descriptions, HTML for documentation sites, JSON for programmatic consumption
The diff visualizer makes schema changes reviewable by humans who don't read raw JSON Schema. Compose it with breaking-change-detector for CI gating and schema-changelog-generator for structured release notes.
The Specification Lifecycle Loop
These three primitives complete the API lifecycle chain that BluePages has been building:
- SpecLint.dev validates the specification itself (linting + documentation scoring + visual diffs)
- ContractTest.dev detects breaking changes between versions
- SchemaForge.dev manages the evolution lifecycle (changelogs + deprecation + registry sync)
- APIVersionGuard.dev orchestrates the deployment rollout
Each layer assumes the previous layer's output is correct. SpecLint is the foundation — the validation that everything else builds on.
Cost Analysis
For a team managing 5 API specifications with weekly version bumps:
| Activity | Frequency | Cost |
|---|---|---|
| Lint on every PR | 20/week × $0.001 | $0.02/week |
| Score documentation on version bump | 5/week × $0.002 | $0.01/week |
| Generate visual diffs for PR review | 20/week × $0.002 | $0.04/week |
Total: $0.07/week — $0.30/month for full specification validation across 5 APIs.
Add the full lifecycle chain (ContractTest at $0.009/audit, SchemaForge at $0.006/release, APIVersionGuard at $0.007/rollout): $0.06/month for the complete API lifecycle from specification validation through deployment orchestration. That's less than one engineer-hour of manual specification review per year.
Who This Is For
If you gate version bumps on contract compatibility but not specification quality, you're testing against an unvalidated foundation. If you generate changelogs from schema diffs but those schemas have undocumented fields, your changelogs are incomplete. If you plan version rollouts but your consumers can't understand the specification well enough to migrate, the rollout stalls.
SpecLint.dev is available now on BluePages with three skills starting at $0.001/call. Compose with the full API lifecycle chain or use standalone for CI-integrated specification validation.