Skip to main content

ADR-008: Versioning Strategy

Status: Accepted Date: 2026-03-20

Context​

The protocol will evolve. New signal types, new metadata fields, and new capabilities will emerge. The versioning strategy determines how the protocol changes without breaking existing agents and trust authorities.

Decision​

Use URL path versioning. The API version appears in the URL path: /v1/entities/{entityId}/trust-signals, /v2/entities/{entityId}/trust-signals.

Version Semantics​

A new major version (v1 → v2) indicates a breaking change:

  • Removed or renamed fields
  • Changed response structure
  • Altered authentication requirements
  • Modified discovery format

Non-breaking changes do not require a version bump:

  • New optional fields in responses
  • New signal types in the taxonomy (ADR-003)
  • New optional query parameters
  • Additional error codes

Coexistence​

The trust authority MUST support the current version and MAY support previous versions simultaneously. When a version reaches end-of-life, the authority returns 410 Gone with a message indicating the supported versions.

Version in Discovery​

The <link rel="trstd-protocol"> tag carries the verify endpoint URL with the major version path baked in (e.g., /v1/entities/{entityId}/trust-signals). Agents use the full URL from the href — they do not construct version paths themselves. Version changes propagate by updating the link tag, not agent code.

A /.well-known/trstd.json manifest with a top-level semver version field and a capabilities array is roadmap material (see ADR-001). When the manifest lands, its major version will correspond to the URL path version; minor and patch versions will signal spec refinements within a major version for feature detection.

Expected Version Frequency​

Most protocol evolution happens through new signal types (ADR-003). These are additive and do not require a version bump. Major version changes should be rare — the signal envelope (type, verifiedAt, data) is designed to accommodate new content without structural changes.

Options Considered​

A. URL path versioning (chosen). /v1/entities/{entityId}/trust-signals, /v2/entities/{entityId}/trust-signals. Explicit and visible. Easy to route at the infrastructure level (load balancers, API gateways). Clear which version an agent targets. URLs change between versions, but the discovery file provides the full URL — agents do not hardcode paths.

B. Header-based versioning. Accept: application/vnd.trstd.v1+json. Clean URLs. Content negotiation is standard HTTP. Less visible in logs and debugging tools. Agents and authorities must implement content negotiation correctly — more room for subtle errors.

C. Additive-only changes. Never break backward compatibility. No version negotiation needed. Constrains evolution — fields cannot be removed or restructured. Accumulated technical debt over time. Works until it doesn't, and then there is no migration path.

Consequences​

  • The URL path makes the version explicit in every request
  • Infrastructure can route versions independently (canary deployments, gradual migration)
  • The trust authority runs multiple versions during transition periods
  • The link tag insulates agents from URL construction — version changes require updating the link tag's href, not agent code
  • Combined with the extensible signal taxonomy, version bumps should be infrequent

References​

  • ADR-001 — Discovery Mechanism (link tag carries the versioned endpoint URL)
  • ADR-002 — Verification Endpoint Schema (endpoint URL structure)
  • ADR-003 — Trust Signal Taxonomy (open taxonomy reduces need for version bumps)