Schema Stability Guarantee
The v1 API schema is stable. This page defines exactly what that means, what is frozen, and how future changes will be communicated.
All fields, enum values, and field semantics documented here are frozen for the lifetime of v1. No existing field will be removed. No existing enum value will be removed or renamed. Field semantics will not change in a breaking way. v1 will be supported for a minimum of 24 months after any v2 announcement.
Attestd is designed to be wired into automated systems: CI/CD pipelines, AI agents, policy engines, and security dashboards. Those integrations must not break silently when the API evolves. This guarantee exists so that code written against v1 today can remain unchanged indefinitely.
Frozen enum — five values, no additions
The risk_state field returns exactly one of five string values. This vocabulary is closed. No new values will be added to v1. If a new risk classification concept requires a sixth value, it will appear in a new field, not in risk_state.
| Value | Meaning |
|---|---|
critical | Actively exploited, remote, unauthenticated. Immediate action required. |
high | Remote exploitable or actively exploited without all three critical flags. |
elevated | Network-accessible with notable CVE severity but without active exploitation. |
low | Local or low-severity CVEs with limited exploitability. |
none | No CVEs affecting this version, or all CVEs are patched and not actively exploited. |
Classification uses worst-case aggregation across all matching CVE version ranges. See the response field reference for full aggregation semantics.
Stable vocabulary — new values are additions, not replacements
The risk_factors array contains zero or more string values from the vocabulary below. The five values listed here are stable: they will not be removed or renamed. If a new risk concept is introduced in v1, it will be added as an additional value. Clients must ignore unknown values to remain forward-compatible.
| Factor | Condition |
|---|---|
active_exploitation | actively_exploited = true |
remote_code_execution | remote_exploitable = true |
no_authentication_required | (actively_exploited OR remote_exploitable) AND authentication_required = false |
internet_exposed_service | remote_exploitable = true AND authentication_required = false |
patch_available | patch_available = true |
All v1 fields and their semantics are frozen
The following fields are present in every supported-product response and will remain present with unchanged semantics for the lifetime of v1.
supportedproductversionrisk_staterisk_factorsactively_exploitedremote_exploitableauthentication_requiredpatch_availablefixed_versionconfidencecve_idslast_updatedsupply_chainUnsupported products return only { supported: false }. This shape is also frozen.
Additive changes only
The following changes are compatible with this guarantee and may happen without a version bump or advance notice:
- New optional fields added to the response object. Clients must ignore unknown fields. This is standard JSON practice and required for forward compatibility.
- New values added to the
risk_factorsarray vocabulary, after announcement. Clients that switch on known values and ignore others are safe. - Improvements to data quality that change the value of existing fields (for example, a
confidencescore improving from 0.5 to 0.9 as LLM extraction improves for a product). These are not breaking changes.
Breaking changes (field removals, enum value removals, semantic changes to existing fields) require a new major API version.
v2 announcement and transition
If a v2 is introduced, v1 will remain supported for a minimum of 24 months from the announcement date. The announcement will include a migration guide and explicit sunset date. v1 and v2 will be available concurrently under distinct base paths (/v1/check and /v2/check).
There is no current plan for a v2.
Machine-readable schema artifact
A versioned JSON Schema (Draft 2020-12) is published at a stable URL. Use it to validate responses in tests, generate typed clients, or configure schema-aware tooling.
2020-12The schema file itself follows the same stability rules: no existing property or constraint will be made more restrictive. New optional properties may be added. The $id URL is permanent.