# How UCP Manages Version Compatibility for Protocols and Capabilities

> Learn how UCP manages version compatibility for protocols and capabilities using declarative JSON Schema. Discover efficient dependency management for your commerce integration.

- Repository: [Universal Commerce Protocol (UCP)/ucp](https://github.com/Universal-Commerce-Protocol/ucp)
- Tags: how-to-guide
- Published: 2026-04-26

---

**UCP isolates protocol-level versioning from capability-level versioning through declarative JSON Schema constructs in [`ucp.json`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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.

```json
{
  "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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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

```json
{
  "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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/schemas/ucp.json).

As documented in [`docs/specification/overview.md`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/schemas/capability.json) (lines 36-40), the `platform_schema` structure combines version metadata with dependency declarations:

```json
{
  "$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:

```json
{
  "$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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/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`](https://github.com/Universal-Commerce-Protocol/ucp/blob/main/source/schemas/capability.json) implements these constraints within the `platform_schema` structure.