Skip to content
Closed
25 changes: 16 additions & 9 deletions docs/specification/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -2236,10 +2236,14 @@ Both businesses and platforms declare a single version in their profiles:

![High-level resolution flow sequence diagram](site:specification/images/ucp-discovery-negotiation.png)

Version compatibility operates at two levels: the **protocol version**
and **capability versions**. The protocol version (`ucp.version`)
governs core protocol mechanisms — discovery, negotiation flow,
transport bindings, and signature requirements. Capability versions
Version compatibility operates at three layers — **transport bindings**,
the **core protocol**, and **capability versions** — each evolving on its
own cadence (see [Versioning](/versioning/#layered-versioning) for the
layer model). The protocol version (`ucp.version`) governs the
cross-cutting mechanisms shared by every transport binding: discovery,
negotiation flow, signature requirements, profile structure, and the
error envelope. Each service entry declares its own `version` and **MAY**
evolve independently of the core protocol cadence. Capability versions
govern the semantics of each feature independently, as defined in
[Independent Component Versioning](#independent-component-versioning).

Expand Down Expand Up @@ -2367,10 +2371,12 @@ support for multiple versions of that capability. The capability
intersection algorithm considers only capability versions supported
by both parties.

Businesses **MUST** include only capabilities compatible with the
negotiated protocol version in their response. A capability that
depends on features introduced in a newer protocol version **MUST
NOT** be included when processing at an older protocol version.
> [!IMPORTANT]
> **Protocol Compatibility Constraint:**
> Businesses **MUST** include only capabilities compatible with the
> negotiated protocol version in their response. A capability that
> depends on features introduced in a newer protocol version
> **MUST NOT** be included when processing at an older protocol version.

### Backwards Compatibility

Expand Down Expand Up @@ -2405,7 +2411,8 @@ The following changes **MUST NOT** be introduced without a new version:
- Capabilities **MUST** follow the same backwards compatibility rules as the
protocol.
- Businesses **MUST** validate capability version compatibility using the same
logic as what's described above.
negotiation logic described in [Protocol Version](#protocol-version) and
[Version Negotiation](#version-negotiation).
- Transports **MAY** define their own version handling mechanisms.

#### UCP Capabilities (`dev.ucp.*`)
Expand Down
31 changes: 30 additions & 1 deletion docs/versioning.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,36 @@
# Versioning

UCP uses date-based version identifiers following the format `YYYY-MM-DD` to
indicate the last date backwards incompatible changes were made.
indicate the last date backwards-incompatible changes were made to a given
component.

## Layered Versioning

UCP versions three layers independently. Each layer evolves on its own
cadence and is negotiated by its own mechanism:

1. **Transport bindings.** Each service entry — REST, MCP, A2A, or
embedded — declares its own `version`. The wire contract for each
transport lives in the OpenAPI / OpenRPC / Agent Card document referenced
from the service entry's `schema` field. Transports **MAY** evolve their
version handling independently from the core protocol release.
2. **Core protocol** (`ucp.version`). Governs the cross-cutting mechanisms
every transport binding inherits: discovery, negotiation flow, signature
requirements, profile structure, and the error envelope. Validated as a
pre-negotiation gate; mismatch returns `version_unsupported`.
3. **Capabilities and extensions.** Each capability entry declares its own
`version`, and each extension that augments a capability versions
independently. Capability versions are intersected at negotiation; the
highest mutual version wins, and extensions **MAY** declare
`requires.protocol` and `requires.capabilities` constraints that further
filter the active set.

For the negotiation algorithm and version-compatibility rules, see
[Version Negotiation](specification/overview.md#version-negotiation) and
[Independent Component Versioning](specification/overview.md#independent-component-versioning)
in the Architecture Overview.

## Release Process

New development occurs on the `main` branch. We will maintain long-lived
branches for all supported releases of the spec.
Expand Down
Loading