Official Python library for the Universal Commerce Protocol (UCP).
This repository contains the Python SDK for the Universal Commerce Protocol (UCP). It provides Pydantic models for UCP schemas, making it easy to build UCP-compliant applications in Python.
Starting with the 2026-08-25 UCP specification release, PyPI releases use
spec-aligned YYYYMMDD.MINOR.PATCH versioning (for example, 20260825.0.0 for
UCP 2026-08-25), while main tracks the draft UCP schema (0.0.0.dev0)
pinned in ucp-lock.json:
| SDK Version | UCP Schema Version | Channel |
|---|---|---|
YYYYMMDD.MINOR.PATCH |
YYYY-MM-DD (>= 2026-08-25) |
PyPI |
0.0.0.dev0 (main git commit) |
draft (ucp@main in ucp-lock) |
Git (main) |
0.5.x |
2026-08-25 |
PyPI (legacy 0.x) |
0.4.x |
2026-04-08 |
PyPI |
0.3.x |
2026-01-23 |
PyPI |
0.2.x / 0.1.x |
2026-01-11 |
PyPI |
Install the latest published UCP release from PyPI:
pip install ucp-sdkOr with uv:
uv add ucp-sdkTo pin a specific UCP specification release epoch (for example, 2026-08-25):
uv add "ucp-sdk>=20260825.0.0,<20260826.0.0"To build against unreleased draft schemas on main, install directly from a
commit SHA on Universal-Commerce-Protocol/python-sdk:
uv add "ucp-sdk @ git+https://github.com/Universal-Commerce-Protocol/python-sdk.git@<commit-sha>"The example below parses a UCP checkout response and reads typed fields:
from ucp_sdk.models import Checkout
# Parse a UCP checkout response
checkout = Checkout.model_validate(checkout_data)
# Access typed fields
print(checkout.status) # "incomplete" | "ready_for_complete" | ...
print(checkout.currency) # ISO 4217 currency code
for item in checkout.line_items:
print(f"{item.item.title}: {item.quantity}")Generated Pydantic models and type aliases for the Shopping vertical
(shopping, common, and transports schemas) are lazily re-exported from
both ucp_sdk.models and ucp_sdk.models.schemas:
| Package | Description |
|---|---|
ucp_sdk.models |
Top-level lazy re-export of all generated UCP models (checkout, cart, order, fulfillment, profile, etc.) |
ucp_sdk.models.schemas |
Lazy re-export of Pydantic v2 models synthesized from the UCP Shopping, Common, and Transports JSON Schema |
Pydantic models in ucp_sdk.models provide Tier 1 wire DTO structural typing
and tolerant-reader deserialization (preserving unknown extension fields for
forward compatibility) rather than full UCP protocol conformance.
In particular, open discriminated unions (such as FulfillmentDestination,
FulfillmentMethod, and Provider) are emitted as untagged unions with an open
*Base fallback (type: str), so payloads carrying a known type
discriminator that fail a variant-specific field constraint will deserialize
into *Base unless validated upfront against the compiled JSON Schema.
To enforce normative UCP constraints (capability profile composition,
directional ucp_request / ucp_response visibility, dependentRequired,
if/then, uniqueItems, contains, propertyNames, not.enum, and
closed-schema rules):
- In-Memory Runtime Validation (Production Services): Compile your UCP
discovery profile once at build or startup time into a standard JSON Schema
Draft 2020-12 bundle
(
ucp-schema generate-types --profile profile.json -o ucp.types.json) or OpenAPI 3.1 specification (ucp-schema generate-openapi --profile profile.json -o openapi.json). Becauseucp-schemaresolves all UCP-specific annotations and capability extensions into standard JSON Schema 2020-12, you can validate incoming payloads in memory on every request usingjsonschema(installpip install "jsonschema[format-nongpl]"to enableurianddate-timeformat validation via MIT-licensed validators without pulling in GPL dependencies) or OpenAPI ASGI middleware before deserializing into Pydantic DTOs:
import json
from pathlib import Path
from jsonschema import Draft202012Validator
from ucp_sdk.models import Checkout
# At startup: load the pre-compiled schema bundle once into memory
bundle = json.loads(Path("ucp.types.json").read_text(encoding="utf-8"))
checkout_validator = Draft202012Validator(
{**bundle["$defs"]["Checkout"], "$defs": bundle["$defs"]},
format_checker=Draft202012Validator.FORMAT_CHECKER,
)
# Per request: validate in-memory, then parse into typed Pydantic DTO
checkout_validator.validate(raw_payload)
checkout = Checkout.model_validate(raw_payload)- CLI & CI Conformance Testing: Verify fixture payloads or live traffic
dumps from the command line or CI pipelines with
ucp-schema validate:
# Self-describing response or JSON-RPC envelope
ucp-schema validate payload.json --op read
# REST request against a discovery profile (or --schema checkout.json --request --op create)
ucp-schema validate payload.json --profile profile.json --op createThis project uses uv for dependency management
and ucp-schema
(cargo install ucp-schema) to synthesize the flat $defs bundle for model
generation.
# Clone the repository
git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git
cd python-sdk
# Install dependencies
uv syncThe models are automatically generated from the JSON schemas in the UCP
Specification using ucp-schema generate-types and datamodel-codegen, with
provenance recorded in ucp-lock.json.
To regenerate the models:
uv sync
# Reproduce committed models from the exact commit pinned in ucp-lock.json
./generate_models.sh
# Advance ucp-lock.json and regenerate models from ucp@main (draft channel)
./generate_models.sh --ref main --write-lock
# Pin ucp-lock.json to a release branch
./generate_models.sh --ref release/2026-08-25 --write-lock
# Regenerate models from a local UCP checkout without modifying ucp-lock.json
./generate_models.sh --spec-dir /path/to/ucpThe generated code is automatically formatted using ruff.
Run the test suite with:
uv run python -m unittest discover -s tests -p "test_*.py"We welcome community contributions. See our Contribution Guide for details.
UCP is an open-source project under the Apache License 2.0.