Spec quality & scoring

Every spec Elva scores gets a grade you can actually defend, because the number comes from 30+ deterministic checks, not a vibe. Here is exactly how the review engine turns your OpenAPI spec into a percentage and a letter grade, so you trust the score before you expose an API to agents.

The four categories that make your score

The review engine runs every check against your parsed spec and rolls the results into four weighted categories: Design, Developer Experience, AI Readiness, and Security. Design carries the most weight, because a poorly shaped API breaks agents and humans alike. AI Readiness is scored explicitly, so an "agent-ready" claim is earned, not assumed.

Design

Weight 40. URI naming, HTTP method semantics, status codes, pagination, versioning, idempotency, and response completeness. The heaviest category, because a poorly shaped API breaks agents and humans alike.

Developer Experience

Weight 35. Executable examples, operation and parameter descriptions, a consistent error model, and overall spec integrity. The category that decides how fast a human ships against your API.

AI Readiness

Weight 15. OperationId quality, semantic descriptions, schema richness, constraints, enum docs, and format specification. How well an LLM can ground itself in your spec.

Security

Weight 10. HTTPS enforcement, declared auth schemes, strong auth methods, 401/403 coverage, rate-limit docs, and secret hygiene. The checks your security review runs anyway, run early.

How a score is computed

Each check returns one of three outcomes, and each outcome carries a fixed multiplier against that check’s weight:

A category’s percentage is the weighted pass ratio: the sum of outcome × weight for its checks, divided by the total weight of those checks. The overall score is the category-weighted average across all four categories, using the 40 / 35 / 15 / 10 weights above.