diff --git a/docs/specification/overview.md b/docs/specification/overview.md index 452e7a5b7..b7ddc0286 100644 --- a/docs/specification/overview.md +++ b/docs/specification/overview.md @@ -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). @@ -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 @@ -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.*`) diff --git a/docs/versioning.md b/docs/versioning.md index 5366b5017..a73a90094 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -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.