Open-source project
Universal-Commerce-Protocol/ucp avatar
Universal-Commerce-Protocol/ucp

UCP: date based versions, a generated schema, and an undefined AP2

Specification and documentation for the Universal Commerce Protocol (UCP)

3,499 stars497 forksPythonApache-2.0

At a glance

What is it?
The Universal Commerce Protocol repository is a specification with three toolchains and one unstated author, where the version scheme is a date written two different ways, the schema you implement against is generated at run time by a Rust tool in another repository, and the security claim depends on an AP2 term the page defines nowhere.
Who is it for?
Read the specification rather than the README if you are evaluating it, because the README is a positioning document and the specification site is where the actual definitions sit. Two things to settle before you build.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Universal-Commerce-Protocol/ucp3,499 ★ · +110
Star history
Repository2026-09-242026-11-14
Universal-Commerce-Protocol/ucp3.4k3.5k

110 Stars in the last 51 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Versions are date based, and the manifest uses dots where the tags use dashes

Three releases are on record and none of them uses a semantic version. They are v2026-01-23, v2026-04-08 and v2026-08-25, so the version is the date it was cut, spaced at roughly a quarter.

The manifest uses the other punctuation. The Python project file declares version 2026.01.23, with dots. So the same release is v2026-01-23 in the tag list and 2026.01.23 in the project metadata, and a tool that resolves a version by string comparison has to pick one form.

The manifest is also two releases out of date. It still says 2026.01.23 while 2026-04-08 and 2026-08-25 have both been published, so anything that reads the version out of the project metadata is reading a number from January. The last commit to the branch is 2026-10-03, two days before the newest tag.

Date-based versioning is a reasonable choice for a specification, because it makes recency legible at a glance and avoids the argument about whether a schema change is breaking. The cost is that there is no minor line to pin to. You take a date, and the next one is another quarter away.

The governance picture is the thinner one. The README names no author, no steward and no governing body. The file header carries an Apache 2.0 copyright line reading UCP Authors, the contributing guide is linked into a separate .github repository, and the maintainers list is linked the same way even though a MAINTAINERS.md also sits at this repository's own root. For a document whose stated purpose is to be the common language between businesses, payment providers, credential providers and agents, the page never says who decides what goes in it.

The security claim rests on AP2 mandates and verifiable credentials, and neither term is defined

The Why UCP section lists four aims. One of them is enhancing security, and its entire text is support for advanced security patterns like AP2 mandates and verifiable credentials.

That is the whole security argument in the README, and it consists of two terms the page does not define, does not link, and does not say who operates. AP2 appears exactly once. A mandate, in that phrasing, is presumably an object one party issues and another honours, but the README never says what issues one, what it contains, or what happens when it is not honoured. Verifiable credentials are equally undefined here.

The same pattern runs through the Key Features list. One bullet says UCP leverages existing open standards for payments, identity and security wherever applicable, rather than reinventing the wheel. That is a good principle and it is also a delegation: the security of the system is the security of whatever AP2 is, and if the reader does not already know AP2 they cannot evaluate the claim.

What the README does do is name the standards it does depend on elsewhere. Identity Linking is described as obtaining authorization to act on a user's behalf via OAuth 2.0. Order updates arrive by webhook. Capabilities can be served over REST, the Model Context Protocol, or A2A. So four concrete, named mechanisms are documented.

The one that carries the most weight, AP2, is the one with no definition and no link. For a checkout protocol handling payments on an agent's behalf, that is the gap worth closing first in the documentation.

Four capabilities use four different interaction patterns and none of them describes moving money

The initial release defines four capabilities, and it is worth reading them side by side because they do not resemble each other.

Checkout facilitates checkout sessions, including cart management and tax calculation, and it says explicitly that it supports flows with or without human intervention. That is a request and response conversation with a party in the middle sometimes.

Identity Linking lets a platform obtain authorization to act on a user's behalf via OAuth 2.0. That is a delegated grant, and the interesting party is the user rather than the merchant.

Order is webhook-based updates for order lifecycle events: shipped, delivered, returned. That is the merchant pushing at the platform, the reverse direction from Checkout, and it means the platform has to expose an endpoint and handle retries.

Payment Token Exchange is described as protocols for Payment Service Providers and Credential Providers to securely exchange payment tokens and credentials. That is neither of the other two parties at all; it is infrastructure talking to infrastructure.

Now the gap. Four capabilities, four interaction patterns: a session, a delegated authorization, a server-to-server callback, and a token exchange between two backends. And nothing in the README says how a payment token becomes a charge, which party initiates it, what happens when a credential provider and a payment service provider disagree, or where the money moves.

For a reader deciding whether to implement this, the token exchange is the interesting one and also the least described, because the two parties it names are not the two parties an application developer is.

Transport agnostic means REST, MCP or A2A, with no statement about which capabilities run on which

One of the five key features is that the protocol is transport agnostic. The text says businesses can offer capabilities via REST APIs, the Model Context Protocol, or A2A, depending on their infrastructure.

That is a useful commitment, because those three are genuinely different worlds. REST is request and response with a schema. The Model Context Protocol is tool calls inside an agent conversation. A2A is agent to agent delegation. Putting the same capability on all three means writing it three times, or having a layer that projects one onto the others.

The README does not say which. There is no table of capability by transport, and the four capabilities are described without reference to any transport at all. Checkout, Identity Linking, Order and Payment Token Exchange are all written as if there were one way to express them.

There is a hint about one of them. Order is webhook-based, and a webhook is not a request and response pattern at all; it is an unsolicited POST to an endpoint the platform has to host. So even inside the specification, at least one capability has an interaction shape that does not map neatly onto a transport-agnostic capability definition.

Two other phrases sit beside it without elaboration. One feature says platforms can autonomously discover and configure themselves from a declared capability profile. The word autonomously is doing real work there, since it means an agent reads a profile and decides how to integrate, and nothing in the README says what constrains that decision or what a platform is expected to refuse.

The schema tool is a Rust binary, the documentation is Python, and the type generation is Node

The primary language recorded for this repository is Python. The repository also contains a Rust tool, a Node toolchain, and a documentation site. The schema development instructions make the Rust part explicit. To work on the schemas you install a binary:

bash
   cargo install ucp-schema                 # from crates.io
   cargo install --git https://github.com/universal-commerce-protocol/ucp-schema  # from git
   

Then you edit JSON files in source/ and run a lint command over that directory to validate syntax and references. The tool is called ucp-schema, it lives in its own repository, and it is distributed on crates.io.

So the tool that validates the specification is a compiled Rust program, in a Python project, validating JSON that describes a protocol meant to be read by agents written in anything.

The documentation side is Python. It uses uv for dependencies, mkdocs to serve, and mkdocs build with a strict flag before submitting, which turns warnings into failures and is the one quality gate the README actually specifies.

The Node side is the least described of the three, because the README never mentions it. The Node manifest has exactly one runtime dependency, a JSON Schema to TypeScript compiler, plus two linting packages. So there is a step somewhere that turns the JSON schemas into TypeScript types, and that step is not in the README's schema development list, which goes from editing source/ straight to running the Rust linter.

Three languages for a repository whose published artefacts are JSON and Markdown is not a problem in itself. The gap is that one of the three pipelines is undocumented.

The schema you implement against is generated at runtime by a tool in another repository

This is the single most consequential design decision in the repository, and it is stated in four sentences.

Schemas live in source/ and are published with ucp prefixed annotations intact. Agents, meaning AI assistants or platforms taking part in the protocol, use the schema tool to resolve those annotations at run time. That resolution produces operation-specific schema variants, for create, update or read operations, from the master schemas. The stated benefit is that a consumer only processes the fields relevant to the current action and direction, request or response.

So what is published is not the schema you code against. What is published is the annotated master, and the thing your implementation actually reads is produced by running a binary, at run time, from a different repository.

That has real consequences for anyone building against UCP. Your field list depends on a generator's version. The two documented install lines make that version ambiguity explicit, because one installs from crates.io and one installs from the git repository, and neither pins a release. A consumer who installs the crates.io build and a consumer who installs the git tip can generate different variants from the same master schema, with nothing in the protocol to distinguish the two.

The README's own argument for the design is that agents should not have to process irrelevant fields, which is a genuine concern when a schema is read by a model rather than by a compiler. The cost is that the contract between a business and a platform now includes a code generator's behaviour, and interoperability now depends on version agreement about a tool that is not part of the specification.

The Node manifest declares Yarn Classic and ships npm's lockfile

The Node manifest in this repository is short and has three notable things in it.

It declares a package manager field pinning Yarn at version 1.22.22, with a hash. Yarn 1 is Yarn Classic, the generation before the current one. The modern major versions are numbered from two upwards, and Classic is the one that reaches end of life.

It ships a lockfile named package-lock.json, which is npm's lockfile. So the manifest names one package manager and the repository contains the other one's lockfile. A file named yarn.lock does not appear at the top level.

And it carries a block of overrides for four transitive packages: two pinned to exact versions, two given as caret ranges. Overrides is npm's mechanism for forcing a transitive dependency's version. Yarn Classic's equivalent is called resolutions and is a different field name. So the four forced versions are written in the dialect of the package manager whose lockfile is committed, inside a manifest that declares the other one.

Whichever of the two a contributor actually runs, the other's lockfile is ignored, and if it is npm then the overrides apply and if it is Yarn Classic then they may not. Nothing in the repository notes which is intended.

The override block also has no explanation. Four transitive packages are being forced to specific versions in a repository that otherwise explains its choices carefully, and there is no comment saying whether they are security pins, breakage workarounds, or both.

Seven quality tools run over a repository whose deliverable is JSON and Markdown

List the tooling configuration at the top level of this repository and count the tools: a pre-commit configuration, a Prettier config and ignore file, a Biome config, a Stylelint config, a cspell config and a cspell directory, a link ignore file, a Python lint and format configuration, and a YAML linter pinned in the Python dependency group.

The Python configuration is the most opinionated of them. It sets a line length of 80 and an indent width of 2, which for Python is not the default and is clearly a choice to match a specification repository's JSON and YAML style rather than PEP 8. It selects a broad rule set and then ignores three specific rules, two of which are the mutually exclusive pair about blank lines around a class docstring, which is the standard way to resolve that conflict, and one of which is the ban on print.

Ignoring the print ban while selecting the rule that contains it is coherent, because this repository has main.py at its root and something has to report progress. It is also the kind of decision a reader would want a comment next to.

The Python dependency group is mostly the documentation stack: five MkDocs plugins, which between them handle material rendering, versioning, redirects, site URLs, macros and generation of a text file for language models, plus a model generator, a YAML linter, and PyYAML.

Two configurations deserve a second look. Prettier and Biome overlap in purpose, both formatting and linting the same JavaScript, TypeScript and JSON, and running both over one file set is a choice that usually needs a way to stop them disagreeing. And the spell checker, which for a specification full of invented protocol terms is not a token gesture.

Editorial conclusion

Read the specification rather than the README if you are evaluating it, because the README is a positioning document and the specification site is where the actual definitions sit. Two things to settle before you build. The schema you implement against is generated at run time from an annotated master by a tool you install separately, and the two documented install paths do not pin a version, so pin one and record it. And the security story is delegated to AP2 mandates and verifiable credentials, terms the README does not define or link, which means you cannot evaluate the claim without going outside this repository. Skip it if you need to know who governs the standard, because no author or steward is named on the page.

Frequently asked questions

How does UCP work?

A business declares the capabilities it supports in a standardized profile, and a platform reads that profile and configures itself against it. The initial release defines four capabilities: Checkout, Identity Linking, Order, and Payment Token Exchange. Capabilities can be offered over REST APIs, the Model Context Protocol, or A2A.

Who publishes and maintains the Universal Commerce Protocol?

The README states no author, steward or governing body. The file header carries an Apache 2.0 copyright line reading UCP Authors, and the contribution guide and maintainers list are both linked from a separate .github repository, even though a MAINTAINERS.md also sits at this repository's root.

How does UCP handle payment?

One of the four capabilities is Payment Token Exchange, described as protocols for Payment Service Providers and Credential Providers to securely exchange payment tokens and credentials. The README does not describe a charge or a settlement step, and does not say which party moves the money.

How do I validate changes to the UCP schemas?

Edit the JSON files in source/ and run ucp-schema lint source/ to validate syntax and references. The tool is a Rust binary installed either with cargo install ucp-schema from crates.io or from its git repository, and the README pins neither version.

How do I build the UCP documentation site?

With uv: run uv sync, then uv run mkdocs serve --watch source for a preview on http://127.0.0.1:8000, and uv run mkdocs build --strict before submitting. The README also offers ./scripts/build_local.sh which it says builds the full site including spec versions.

Official sources

  1. License: Apache-2.0
  2. Project website
  3. README
  4. Releases
  5. Universal-Commerce-Protocol/ucp on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/universal-commerce-protocol-ucp.svg)](https://hysenlabs.com/projects/universal-commerce-protocol-ucp)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/universal-commerce-protocol-ucp.svg)](https://hysenlabs.com/projects/universal-commerce-protocol-ucp)

Was this useful?