← Articles

UCP Version Negotiation Overhaul: Business-Canonical Versioning

Ilya Grigorik's comprehensive PR #200 fundamentally reshapes how protocol versioning works — businesses declare what they support, platforms must match, and extensions can declare dependency constraints.

Why This Matters

Protocol versioning sounds mundane until you realize it determines whether an AI agent can actually transact with a business. The prior UCP model imposed an unbounded backwards-compatibility obligation: businesses had to process any request from a platform using an older protocol version. Forever.

That's unsustainable. PR #200 flips the model: the business's protocol version is canonical. Platforms must support what businesses declare. This seemingly simple inversion has profound implications for how the ecosystem evolves.

What Changed Technically

The PR introduces four major changes:

1. Business-Declared Version Support

Businesses now declare accepted versions via a supported_versions array in their profile:

{
  "protocol_version": "2026-03-01",
  "supported_versions": {
    "2026-01-23": "/.well-known/ucp/2026-01-23",
    "2025-09-15": "/.well-known/ucp/2025-09-15"
  }
}

Each entry points to a complete, self-contained profile for that version. The current version is served at the root; only older versions appear in the map. Version-specific profiles are leaf documents with no further supported_versions nesting.

2. Version Mismatch Becomes Protocol Error

Previously, version_unsupported was a negotiation result (HTTP 200 with checkout message schema). Now it's a protocol error (HTTP 422). The reasoning: version mismatch is a pre-negotiation gate check — the buyer cannot resolve a protocol incompatibility. It's not a business outcome; it's infrastructure failure.

3. Capability Version Intersection

The capability intersection algorithm now explicitly handles version selection:

// Intersection algorithm additions:
// 1. Compute mutual version set for each capability
// 2. Select highest mutual version
// 3. Exclude capability if no mutual version exists

This prevents the ambiguity of "I support checkout, you support checkout, but we're using different checkout versions with incompatible semantics."

4. Extension Schema Version Constraints

Extensions can now declare dependencies via a requires object:

{
  "requires": {
    "protocol": { "min": "2026-01-23" },
    "capabilities": {
      "dev.ucp.shopping.checkout": { 
        "min": "2026-06-01",
        "max": "2026-12-01"
      }
    }
  }
}

Why capability constraints? Third-party extensions move on their own release schedule. When com.acme.loyalty extends dev.ucp.shopping.checkout, it depends on checkout's semantic contract as of a specific version. Schema validation catches structural mismatches, but can't catch semantic changes — fields changing units, enum values shifting meaning, behavioral contracts tightening.

The extension author declaring "I understand checkout's contract as of version X through Y" is the only defense against silent semantic bugs.

Design Philosophy

Several key decisions shaped this PR:

• URI-reference format: The supported_versions map uses relative URIs, allowing /.well-known/ucp/2026-01-11 style paths without requiring absolute URLs.
• Version lifecycle is business policy: The protocol does not prescribe deprecation schedules. Some businesses may support five versions; others may only support current. That's a business decision, not a protocol mandate.
• min/max for extensions: An extension tested against checkout 2026-01-23 through 2026-09-01 should not silently claim compatibility with 2026-12-01 if breaking changes landed. Both floor and ceiling matter.
• MUST over SHOULD: After review feedback, min_protocol_version validation was upgraded from SHOULD to MUST — implementations must verify negotiated version against extension requirements.

Implications for the Ecosystem

For Platforms

Platforms now carry the version support burden. This is appropriate — there are far fewer platforms than businesses, and platforms are sophisticated technical operations that can maintain compatibility shims.

For Businesses

Freedom to evolve. Businesses can drop support for older versions without breaking the ecosystem, as long as they give platforms time to adapt. The supported_versions map makes deprecation explicit and discoverable.

For Extension Authors

New responsibility: explicitly declare what you depend on. The requires object forces extension authors to think about versioning upfront, preventing "works on my version" deployment failures.

Connection to Prior Work

This PR builds on Grigorik's systematic UCP contributions:

• Status discriminator (Feb 28): Semantic error handling that enables this version mismatch reclassification
• Message signing (Feb 18): Cryptographic verification that benefits from clear version contracts
• Risk signals (Feb 4): Protocol-level trust signals that work across versions

Together, these form UCP's maturity infrastructure — the boring but essential work that makes enterprise adoption possible.

Next Steps

The PR merged on March 7, 2026. Key follow-up work:

• Platform implementations need to adopt the new discovery flow
• Business profiles need to migrate to the supported_versions format
• Extension authors should add requires declarations to existing schemas
• Documentation updates to reflect the new version negotiation model

This is the kind of change that determines whether a protocol scales from demo to production. Unsexy, essential infrastructure.