How UCP Manages Version Compatibility for Protocols and Capabilities

UCP isolates protocol-level versioning from capability-level versioning through declarative JSON Schema constructs in ucp.json, allowing businesses to advertise supported protocol versions while capabilities declare dependencies using minimum and maximum version ranges.

The Universal Commerce Protocol (UCP) employs a dual-layer versioning strategy that prevents breaking changes in the core specification from disrupting individual feature capabilities. According to the Universal-Commerce-Protocol/ucp source code, this system uses date-based protocol identifiers and semantic dependency ranges defined in JSON Schema to ensure interoperability between commerce platforms and business profiles.

Protocol-Level Versioning

UCP versions its entire specification using date-based version strings in YYYY-MM-DD format. In source/schemas/ucp.json, the top-level version field (lines 8-12) stores this identifier within a business profile discovered at /.well-known/ucp.

Businesses can maintain backward compatibility by populating the supported_versions map (lines 82-90). This object maps protocol dates to URIs hosting version-specific discovery profiles, allowing platforms to locate the exact schema set they need.

{
  "supported_versions": {
    "2025-01-01": "https://business.example.com/.well-known/ucp/2025-01-01.json",
    "2026-04-26": "https://business.example.com/.well-known/ucp/2026-04-26.json"
  }
}

Capability-Level Version Constraints

Individual capabilities declare their compatibility requirements using the version_constraint definition (lines 14-27 in ucp.json). This reusable schema accepts min and optional max properties forming a semantic range that the consuming protocol or capability must satisfy.

Capabilities express dependencies through the requires object (lines 31-46), which contains:

• A protocol constraint specifying minimum/maximum UCP specification versions
• A capabilities map where keys are reverse-domain capability names and values are version_constraint objects

{
  "requires": {
    "protocol": {
      "min": "2026-01-01"
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": {
        "min": "2026-01-01"
      },
      "dev.ucp.shopping.cart": {
        "min": "2025-12-15",
        "max": "2026-04-25"
      }
    }
  }
}

Discovery and Compatibility Negotiation

The discovery flow resolves version compatibility in two distinct phases. First, the platform requests the business profile and inspects the version field to determine the protocol version. If the platform requires a different date, it consults supported_versions to fetch the appropriate profile URI.

Once the protocol version is fixed, the platform evaluates each capability's requires.protocol and requires.capabilities fields against the available environment. This verification happens before invocation, ensuring that dependency chains are fully satisfied according to the constraints defined in source/schemas/ucp.json.

As documented in docs/specification/overview.md, this negotiation process ensures that protocol compatibility is established before capability compatibility is checked, preventing runtime failures due to schema mismatches.

Declaring Version Requirements in Practice

When defining a capability in source/schemas/capability.json (lines 36-40), the platform_schema structure combines version metadata with dependency declarations:

{
  "$ref": "#/$defs/platform_schema",
  "version": "2026-04-26",
  "spec": "https://ucp.dev/2026-04-26/specification/checkout",
  "schema": "https://ucp.dev/2026-04-26/schemas/shopping/checkout.json",
  "requires": {
    "protocol": { "min": "2026-04-01" },
    "capabilities": {
      "dev.ucp.shopping.cart": { "min": "2026-04-01" }
    }
  }
}

The version_constraint definition can be referenced directly when declaring range requirements:

{
  "$ref": "ucp.json#/$defs/version_constraint",
  "min": "2025-09-01",
  "max": "2026-04-30"
}

Summary

• Date-based protocol versioning: UCP uses YYYY-MM-DD strings in ucp.json to version the core specification, with businesses advertising supported dates via the supported_versions map.
• Semantic range constraints: The version_constraint definition in source/schemas/ucp.json enables min and max versioning for both protocol and capability dependencies.
• Declarative dependency chains: Capabilities declare requirements through the requires object, specifying compatible protocol versions and dependent capability versions using reverse-domain keys.
• Two-phase discovery: Platforms first negotiate the protocol version using version and supported_versions, then validate capability constraints before invocation.

Frequently Asked Questions

How does UCP differentiate between protocol and capability versions?

Protocol versions identify the core UCP specification using dates (e.g., 2026-04-26), while capability versions track individual feature implementations. The protocol version appears in the top-level version field of ucp.json, whereas capability versions are constrained through the requires.capabilities map using semantic ranges.

What happens during the version discovery process?

The platform retrieves the business profile from /.well-known/ucp and checks the version field. If the platform requires a different protocol date, it searches the supported_versions map for a matching URI. After selecting the protocol version, the platform validates that all capability dependencies satisfy their declared version_constraint ranges before executing any commerce functions.

Can a business support multiple UCP protocol versions simultaneously?

Yes. By populating supported_versions in ucp.json (lines 82-90), a business can maintain separate discovery profiles for different protocol dates. This allows older platforms to interact using legacy protocol versions while newer platforms access current capabilities, with deprecation policies managed by the business rather than enforced by the protocol.

Where are version constraints defined in the UCP schema?

Version constraints are defined in source/schemas/ucp.json as the version_constraint reusable definition (lines 14-27), which specifies min and optional max date strings. The requires field (lines 31-46) uses this definition to declare both protocol and capability dependencies, while source/schemas/capability.json implements these constraints within the platform_schema structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}