An OpenAPI validator does two related but distinct jobs: tell you whether the spec parses as valid OpenAPI, and tell you whether it follows the conventions your SDK and docs generators actually need. The first is a binary pass/fail. The second is a style guide. Most validation pain in 2026 is on the second job — your spec validates fine, but the generated SDK still feels wrong because the spec used patterns the generator can't render cleanly.
This post compares five validators on the dimensions that matter when you're trying to ship SDKs and docs from one OpenAPI file: schema correctness, naming hygiene, completeness for codegen, security coverage, and CI ergonomics.
The five tools
- Spectral — Stoplight's open-source linter. The de facto standard for opinionated rule packs.
- Redocly CLI — Redocly's bundled linter and validator, ships with a strong built-in ruleset.
- Speccy — archived since 2021. Listed here only because you'll see it referenced in older blog posts and Stack Overflow answers; treat as legacy and prefer Spectral.
- swagger-cli — the original validator. Strictly schema correctness, no style rules.
- Bloom spec scanner — what Bloom runs on every spec push in the dashboard. Focused on SDK-generation readiness, not generic linting.
What each catches
| Concern | Spectral | Redocly | openapi-cli | swagger-cli | Bloom |
|---|---|---|---|---|---|
| OpenAPI schema validity | ✅ | ✅ | ✅ | ✅ | ✅ |
Missing operationId |
✅ (rule) | ✅ (rule) | partial | ❌ | ✅ (always) |
Inconsistent operationId casing |
✅ (custom) | ✅ (rule) | ❌ | ❌ | ✅ |
| Schema reuse vs inline duplication | ✅ (custom) | ✅ (rule) | ❌ | ❌ | ✅ |
| Examples on every operation | ✅ (rule) | ✅ (rule) | partial | ❌ | ✅ |
| Security scheme defined and applied | ✅ (rule) | ✅ (rule) | partial | ❌ | ✅ |
| OpenAPI 3.0 vs 3.1 compatibility check | partial | ✅ | ❌ | partial | ✅ |
| Will-this-generate-good-TypeScript? | ❌ | ❌ | ❌ | ❌ | ✅ |
| Will-this-generate-good-Python? | ❌ | ❌ | ❌ | ❌ | ✅ |
The first six rows are what every validator should cover. The bottom two are what general-purpose validators don't — they can tell you the spec is valid but not that the generated SDK will be ergonomic in any given language.
Picking a validator: three honest paths
Path 1 — Spectral in CI, free
Best if you want a portable, open-source linter that runs anywhere. Drop a .spectral.yaml at the root of your repo with the rule pack you want (or extend Spectral's built-in spectral:oas ruleset). Run spectral lint openapi.yaml in CI on every PR. Add rules as your team finds patterns worth enforcing.
What you give up: Spectral catches what you tell it to. Out of the box it's good, but the rules that actually move the needle on SDK quality (consistent operationId casing, schema reuse, example coverage) are not in the default pack. You will spend a Friday writing custom rules.
Path 2 — Redocly CLI for a complete pre-bundled experience
Best if you want strong defaults without writing rules. Redocly's built-in ruleset is opinionated, well-tuned for docs generation, and integrates with their docs hosting. redocly lint openapi.yaml in CI gives you a strong baseline immediately.
What you give up: Some rules are tied to Redocly's docs conventions and feel arbitrary if you're not on Redocly. You can disable them, but you're now maintaining the disabled list.
Path 3 — Bloom for SDK + docs together
Best if your goal is to ship a working SDK from the spec, not just to validate it as syntactically clean OpenAPI. Bloom's scanner runs on every spec push in the dashboard and flags the patterns that produce idiomatic TypeScript and Python code — naming, reuse, examples, auth coverage, response shape — alongside generic OpenAPI validity. Because it runs as part of the workflow that emits the SDK, the feedback loop is "fix this and the SDK will improve" rather than "fix this so the linter passes."
What you give up: It's tied to Bloom's pipeline. If you want a portable rule pack to commit to a repo, use Spectral or Redocly alongside.
A pragmatic stack for 2026
The way most fast-moving API teams actually run validation:
- swagger-cli or Redocly CLI in a git pre-commit hook — catches schema-broken specs before the PR is opened. Sub-second feedback.
- Spectral with a custom rule pack in CI — fails the PR if naming/reuse/examples/security rules aren't met. Caches well in CI.
- Bloom in the dashboard — runs on every spec push and produces a written compatibility report against the previous SDK. Catches SDK-breaking changes before publishing.
You don't need all three. You do need at least one rule-based linter in CI plus a generation-aware scanner before publishing. The middle of the road — schema-only validation in CI with no style rules and no generation-aware check before publish — is where most SDK quality problems get shipped.
What about OpenAPI 3.1 specifically
OpenAPI 3.1 aligned the schema portion with JSON Schema 2020-12, which changes how nullability, tuple validation, and examples are handled. Many validators were slow to catch up; some still incorrectly flag valid 3.1 specs as invalid because their internal schema bundle is stuck on 3.0.
When picking a validator in 2026, verify it explicitly supports 3.1 (not just claims to). Run a known-good 3.1 spec through it. If it complains about type: ["string", "null"] or about examples being an array, the tool is behind the spec.
For a deeper dive on what 3.1 changed and what to do about it, see OpenAPI 3.1 vs 3.0: what to use.
Bottom line
A validator's job isn't to gatekeep — it's to feed back. The best stack is one that gives you fast feedback at commit time (schema correctness), opinionated style feedback in CI (rule pack), and generation-aware feedback before publishing (does this spec produce SDKs your customers will like). Pick one tool from each tier and you'll catch the bugs that actually break customer integrations.
Try Bloom free for 30 days — every spec push runs the SDK-generation-aware scanner and previews the resulting TypeScript and Python SDKs before publishing. Completely free for 30 days. No credit card required.