Versioning & deprecation

One contract version - currently v1.25.0 - reported identically by the OpenAPI spec, the MCP server’s serverInfo, and the MCP server card. It follows SemVer: major means a response-envelope break (a stable field removed, renamed, or changed in meaning, or the default response format flipping); minor means anything additive plus check-catalog membership changes, always with a changelog entry; patch means spec-only corrections. Pinning the major version is safe and recommended.

Nothing is removed silently

When an endpoint, field, or version is scheduled for removal, its responses start carrying a Deprecation header (draft-ietf-httpapi-deprecation-header) the day the decision takes effect, and an RFC 8594 Sunset header once a removal date is committed - always at least 90 days out. Both headers are declared on the primary success responses in the OpenAPI spec (components.headers), so integrations can watch for them mechanically. The migration path is documented here, and the default response shape only flips on a major version.

Gating in CI

Because check tiers are advisory and the required set may grow on a minor release, CI callers should gate on a score threshold or an explicit list of check ids rather than on “all required checks pass”.

Stable fields are frozen within a major: domain, score, scoreMax, grade, layer and check ids, check status, score and maxScore, bonus, analysisStatus, pendingChecks, url, generatedAt, source, and the topFixes array’s presence and entry shape. An id never changes meaning while it exists, though catalog membership (which check ids run) may change on a minor release. Advisory fields (estScoreGain, tier, maturity, recommendation, details, naReason, gradeColor, name, specUrl, and topFixes ordering) may change on any release. Experimental fields (competitors) carry no guarantee.