From b720e368b060a52bd1b5a22f3c0e85039667b6ee Mon Sep 17 00:00:00 2001 From: Guillaume Verdier Date: Wed, 6 May 2026 14:16:51 +0000 Subject: [PATCH 1/3] docs: explain protocol vs capability versioning - Update versioning.md with high-level two-tiered versioning concepts. - Link to detailed specifications in overview.md to avoid duplication. - Add protocol compatibility alert and negotiation links in overview.md. - Fix markdown formatting to pass lint checks. --- docs/specification/overview.md | 10 ++++------ docs/versioning.md | 14 ++++++++++++-- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/specification/overview.md b/docs/specification/overview.md index 535c0ddbd..bd523f419 100644 --- a/docs/specification/overview.md +++ b/docs/specification/overview.md @@ -1971,10 +1971,9 @@ 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 @@ -2008,8 +2007,7 @@ The following changes **MUST NOT** be introduced without a new version: - Each capability versions independently from other capabilities. - 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. +- Businesses **MUST** validate capability version compatibility using the same 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..4760ebcb1 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -1,7 +1,17 @@ # Versioning -UCP uses date-based version identifiers following the format `YYYY-MM-DD` to -indicate the last date backwards incompatible changes were made. +UCP uses date-based version identifiers following the format `YYYY-MM-DD` to indicate the last date backwards-incompatible changes were made. + +## Two-Tiered Versioning + +To balance ecosystem stability with flexibility, versioning in UCP operates at two distinct levels: + +1. **Protocol Version (`ucp.version`)**: Governs core protocol mechanisms (discovery, negotiation, transport, signatures) and uses the date-based `YYYY-MM-DD` format. +2. **Capability Versions**: Govern individual features (e.g., Cart, Checkout, Order) which version independently to allow rapid iteration. Standard UCP capabilities also use the date-based `YYYY-MM-DD` format. + +For details on negotiation, interaction, and lifecycles of these versions, see [Capability Versions](specification/overview.md#capability-versions) 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. From 6f6282d6d51f2fa9acf0edad84e1ee4bf1b12020 Mon Sep 17 00:00:00 2001 From: Ilya Grigorik Date: Thu, 25 Jun 2026 08:17:15 +0200 Subject: [PATCH 2/3] docs: rework versioning explainer as layered model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the two-tiered framing in versioning.md with a three-layer model - transport bindings, core protocol, capabilities and extensions - and reconcile the parallel paragraph in overview.md §Version Negotiation, which previously said the protocol version "governs ... transport bindings". That phrasing contradicts the existing line in §Independent Component Versioning: "Transports MAY define their own version handling mechanisms." The three-layer model matches what the schema and the negotiation algorithm already do: - Transport: each service entry declares its own `version`. The wire contract lives in the OpenAPI/OpenRPC/Agent Card document at the service entry's `schema` field. Not consumed by the intersection algorithm; transports MAY evolve independently. - Core protocol (`ucp.version`): cross-cutting mechanisms shared by every transport binding - discovery, negotiation flow, signatures, profile structure, error envelope. Pre-negotiation gate; mismatch returns `version_unsupported`. - Capabilities and extensions: each capability entry declares its own `version`. Intersected at negotiation; the highest mutual version wins, and extensions MAY declare `requires.protocol` and `requires.capabilities` constraints to further filter the active set. Also: - Fixes a broken cross-reference in versioning.md (`specification/overview.md#capability-versions` -> `#version-negotiation`). - Hard-wraps the Protocol Compatibility Constraint IMPORTANT callout in overview.md §Capability Versions to match the file's ~80-col convention and the existing `> [!NOTE]` style in split-payments.md. --- docs/specification/overview.md | 21 ++++++++++++------ docs/versioning.md | 39 +++++++++++++++++++++++++--------- 2 files changed, 44 insertions(+), 16 deletions(-) diff --git a/docs/specification/overview.md b/docs/specification/overview.md index 0fe2bf6fb..cab346dea 100644 --- a/docs/specification/overview.md +++ b/docs/specification/overview.md @@ -1905,10 +1905,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.md#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). @@ -2038,7 +2042,10 @@ by both parties. > [!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. +> 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 @@ -2072,7 +2079,9 @@ The following changes **MUST NOT** be introduced without a new version: - Each capability versions independently from other capabilities. - Capabilities **MUST** follow the same backwards compatibility rules as the protocol. -- Businesses **MUST** validate capability version compatibility using the same negotiation logic described in [Protocol Version](#protocol-version) and [Version Negotiation](#version-negotiation). +- Businesses **MUST** validate capability version compatibility using the same + 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 4760ebcb1..a73a90094 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -1,15 +1,34 @@ # Versioning -UCP uses date-based version identifiers following the format `YYYY-MM-DD` to indicate the last date backwards-incompatible changes were made. - -## Two-Tiered Versioning - -To balance ecosystem stability with flexibility, versioning in UCP operates at two distinct levels: - -1. **Protocol Version (`ucp.version`)**: Governs core protocol mechanisms (discovery, negotiation, transport, signatures) and uses the date-based `YYYY-MM-DD` format. -2. **Capability Versions**: Govern individual features (e.g., Cart, Checkout, Order) which version independently to allow rapid iteration. Standard UCP capabilities also use the date-based `YYYY-MM-DD` format. - -For details on negotiation, interaction, and lifecycles of these versions, see [Capability Versions](specification/overview.md#capability-versions) and [Independent Component Versioning](specification/overview.md#independent-component-versioning) in the Architecture Overview. +UCP uses date-based version identifiers following the format `YYYY-MM-DD` to +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 From 2f1e5cc29d92270ebbf44982aa10c6b112daad09 Mon Sep 17 00:00:00 2001 From: Guillaume Verdier Date: Mon, 29 Jun 2026 14:27:29 +0000 Subject: [PATCH 3/3] docs: use absolute link for versioning to fix build --- docs/specification/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/overview.md b/docs/specification/overview.md index cab346dea..72ab07968 100644 --- a/docs/specification/overview.md +++ b/docs/specification/overview.md @@ -1907,7 +1907,7 @@ Both businesses and platforms declare a single version in their profiles: Version compatibility operates at three layers — **transport bindings**, the **core protocol**, and **capability versions** — each evolving on its -own cadence (see [Versioning](../versioning.md#layered-versioning) for the +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