docs: enrich core-concepts with comprehensive UCP protocol overview by amithanda · Pull Request #336 · Universal-Commerce-Protocol/ucp

amithanda · 2026-04-05T01:15:00Z

Description

Updated docs/documentation/core-concepts.md to provide a more complete, accurate, and generic view of the UCP protocol. The page previously contained only a brief intro and architecture diagram; it now serves as a comprehensive reference for core protocol concepts.

Key changes:

Added terminology note clarifying that Platform/Business roles are defined by direction of capability flow, making UCP applicable to B2C, B2B, and agent-to-agent commerce
Added Core Constructs section covering Capabilities, Extensions, and Services — including code examples, capability/extension tables (with disclaimer that these are examples only), and an explanation of how service namespaces enable future verticals
Added Discovery & Capability Negotiation section covering profile-based discovery, the capability intersection algorithm, profile structure, and permissionless vs. pre-established onboarding
Added Namespace Governance section explaining reverse-domain naming, dev.ucp.* reservation, and vendor-namespace extensibility
Added Payment Architecture section covering the trust triangle, payment handler lifecycle, and credential flow constraints
Added Security & Authentication section covering identity/key discovery, authentication mechanisms (RFC 9421, OAuth 2.0, API Keys, mTLS), and identity linking
Added Versioning section covering date-based versioning, breaking change process, and supported_versions

Type of change

Documentation update

Checklist

My code follows the style guidelines of this project
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
Any dependent changes have been merged and published in downstream modules

- Replace "consumer surfaces/platforms" with "consumer platforms" and "businesses" with "business platforms" for consistency. - Enhance the definitions of consumer and business platforms, emphasizing their roles in capability consumption and exposure. - Revise key goals and responsibilities to reflect updated terminology and clarify the interaction dynamics within the UCP framework. - Introduce a new section on capabilities, detailing their structure and examples to improve understanding of UCP's functionality.

igrigorik

Nice update! Some suggestions and bugfixes...

igrigorik · 2026-04-08T17:10:02Z

-    way without building custom integrations for every platform.
-* **Payment & Credential Providers:** To securely exchange tokens and
-    credentials to facilitate transactions.
+* **Consumer Platforms:** To dynamically discover and consume the capabilities business platform exposes.


We're now reusing platform across consumer and business, which is confusing. I think previous headings were better, but new text is good.

Platforms: ...

Businesses: ...

Payment & Credential Providers: ...

I tend to agree with @igrigorik that we should avoid using "platform" as an optional qualifier for a Business if there is the definitive "Platform" (the consumer of capabilities) that is already established above.

The reason I was planning to move away from just Platforms & Businesses is that for future B2B use cases, it is going to be confusing when one business is a consumer of a service and other business is a provider of service. Many businesses consider themselves "Platforms" so it does not disambiguate clearly. Take a B2B example of Logistics provider and retailer, both are businesses, so the platform v/s business separation is not clear enough but if we use consumer platform / business platform, we can highlight the relationship rooted in consumer/provider of capabilities. This helps both B2B, B2C scenarios and in our documentation we can stick to the direction of capability exchanges and make it more generic. Open to more suggestions and thoughts.

Switched to using Platforms and Businesses.

gsmith85

Added some additional comments that push on clarity, but overall looks great.

gsmith85 · 2026-04-09T23:25:38Z

 [Schema Reference](../specification/reference.md).

+!!! note "Terminology"
+    Throughout this documentation, **Platform** (or *consumer platform*) refers to any entity that *consumes* capabilities — an app, an AI agent, a procurement system, or another business. **Business** (or *business platform*) refers to any entity that *exposes* capabilities — a retailer, a supplier, a service provider, or any other participant offering commerce functionality. These roles are defined by direction of capability flow, not by industry vertical, making UCP equally applicable to B2C, B2B, and agent-to-agent commerce. The terms *consumer surface* and *merchant platform* may appear in earlier drafts and community discussions — they are synonymous with Platform and Business respectively.


Within /ucp "merchant platform" only appears in #152 and you're scrubbing all usages of "consumer surface" which only appeared in core-concepts.md. You can likely drop the last line on historical terminology unless you need the continuity with internal documentation.

We discussed during our last TC review and decided to pivot towards using client and provider instead of using Platform and Business to be more futureproof. We aligned that a note is still warranted to avoid any confusion and we can remove it in future. I have made a bunch of changes to the file to conform to the new terms. PTAL again.

after getting a quick sense about the changes it will take to switch to the new terminology, I have reverted back to using Platform and Business. I have removed the additional note as that is no longer need.

gsmith85 · 2026-04-09T23:41:09Z

-    way without building custom integrations for every platform.
-* **Payment & Credential Providers:** To securely exchange tokens and
-    credentials to facilitate transactions.
+* **Consumer Platforms:** To dynamically discover and consume the capabilities business platform exposes.


I tend to agree with @igrigorik that we should avoid using "platform" as an optional qualifier for a Business if there is the definitive "Platform" (the consumer of capabilities) that is already established above.

gsmith85 · 2026-04-10T00:08:06Z

-* **Agentic Commerce:** Enable AI agents to act on behalf of users to complete
-    complex tasks like "Find a headset under $100 and buy it."
+* **Agentic Commerce:** Enable AI agents to act on behalf of any principal —
+    a consumer, an enterprise buyer, or an automated system — to execute


To distinguish between the dimensions at play, consider reframing this as:

Enable AI agents to act on behalf of varied principals (an individual, organization, or another agent) and agentic shopping modalities (human-in-the-loop, fully autonomous).

Made some changes. PTAL.

gsmith85 · 2026-04-10T00:23:03Z

-* **Examples:** Retailers, Airlines, Hotel Chains, Service Providers.
+* **Responsibilities:** Publishing a capability profile, declaring supported
+    services and extensions, processing capability invocations, and managing
+    the transaction or interaction lifecycle.


Between "managing capability sessions" above and "the transaction or interaction lifecycle" here it may be useful to establish standard terminology that captures that (i) capabilities may or may-not be transactional and (ii) capabilities may or may-not be stateful / have an interaction lifecycle. I think it would allow these explanations to be more precise without hedged language.

For illustration, catalog.lookup is non-transactional/stateless, cart is non-transactional/stateful, and checkout is transactional/stateful.

Made some changes. PTAL.

gsmith85 · 2026-04-10T01:02:43Z

-    credentials to facilitate transactions.
+* **Consumer Platforms:** To dynamically discover and consume the capabilities business platform exposes.
+* **Business Platforms:** To declare what they offer and how they operate — once — and have any compatible platform discover and use it without bespoke integrations.
+* **Payment & Credential Providers:** To securely hold sensitive user data and issue tokens or credentials on behalf of users, so that platforms and businesses never handle raw payment or identity information directly.


UCP's identity protection story is really about OAuth delegation (the platform gets an access token, never the user's credentials at the business) so perhaps we say that explicitly, instead of borrowing "raw" which is more footed in payments?

We are actively working on supporting other identity schemes, so I would like to avoid anchoring this in just OAuth delegation. It will get out of date very quickly :)

Made some changes, let me know if they address your feedback.

- Clarified the role of Payment & Credential Providers to emphasize the secure handling of sensitive user data. - Enhanced the description of Agentic Commerce to include various modalities for AI agents. - Revised terminology for distinct actors in the UCP framework to improve clarity. - Updated capability negotiation process to specify version selection and mutual agreement. - Improved examples and descriptions for capabilities and transport bindings to align with current standards.

- Updated terminology to replace "consumer platforms" with "clients" and "business platforms" with "providers" for consistency and clarity. - Enhanced descriptions of the roles and responsibilities of clients and providers in the UCP framework. - Revised key goals and capabilities to reflect the updated terminology and improve understanding of UCP's functionality.

amithanda · 2026-04-11T17:44:31Z

I just tried to get a sense for what a broader change from platform/business to client/provider will mean and it seems besides ~430 changes around 34 files, there are other major complications:

Key complications:

platform-tokenizer-payment-handler.md — "Platform Tokenizer" is a named payment handler pattern, not just a role reference. Renaming it to "Client Tokenizer" changes the meaning of a defined artifact.
HTTP header/field names — UCP-Agent header and schema field names like platform_schema can't be renamed in docs without a corresponding schema breaking change.
platform_schema / business_schema — These are actual JSON schema field names that appear in docs. They must stay as-is.

I think we can stick to platform / business terminology while clearly explaining what they mean so that it is less confusing. Doing these changes will be quite disruptive and break a lot of things.

- Replaced "Client" with "Platform" and "Provider" with "Business" for consistency.

raginpirate

Small feedback related to the payments portions; these changes look great!

raginpirate · 2026-04-22T01:37:12Z

-    credentials to facilitate transactions.
+* **Platforms:** To dynamically discover and consume the capabilities a business exposes.
+* **Businesses:** To declare what they offer and how they operate — once — and have any compatible platform discover and use it without bespoke integrations.
+* **Payment & Credential Providers:** To securely hold sensitive user data and issue tokens or credentials on behalf of users, so that platforms and businesses never handle sensitive payment or identity information directly.


Opinion: I don't think this explanation fits the goal of UCP for Payment credential providers, it reads more like how businesses and platforms are using them. I also think we overreach a bit saying that platforms and businesses are not allowed to handle sensitive context if they want to.

Possible alternative phrasing, zoomed in on what UCP is empowering for payment & credential providers.

Suggested change

* **Payment & Credential Providers:** To securely hold sensitive user data and issue tokens or credentials on behalf of users, so that platforms and businesses never handle sensitive payment or identity information directly.

* **Payment & Credential Providers:** To expose their services — tokenization, vaulting, credential issuance — once, and power secure commerce for users across any compatible platform and business.

raginpirate · 2026-04-22T01:55:56Z

+This architecture keeps raw card data off the platform-to-business API,
+minimizing PCI scope for the platform and reducing compliance surface for the
+overall integration.


nit: this mentions cards and PCI, which is bringing in specific instrument context to an otherwise agnostic conversation. I also think that these points have generally been made already, maybe we can just drop this paragraph entirely? Non-blocking.

raginpirate · 2026-04-22T01:59:25Z

+2. **Platform ↔ Credential Provider (CP)** — The platform acquires a payment
+   instrument (token, encrypted payload) directly from the CP, keeping raw
+   credentials off the platform-to-business API.


Should this be a may? Its very possible to avoid using credential providers in UCP.

Suggested change

2. **Platform ↔ Credential Provider (CP)** — The platform acquires a payment

instrument (token, encrypted payload) directly from the CP, keeping raw

credentials off the platform-to-business API.

2. **Platform ↔ Credential Provider (CP)** — The platform may leverage an independent credential provider to prepare encrypted or tokenized payloads, keeping raw credentials abstracted away from the platform-to-business APIs.

amithanda requested review from a team as code owners April 5, 2026 01:15

amithanda requested review from MitkoDeyanovMitev, aksbro-gpu, igrigorik, richmolj and westeezy April 5, 2026 01:15

igrigorik added this to the Working Draft milestone Apr 8, 2026

igrigorik requested changes Apr 8, 2026

View reviewed changes

Merge branch 'main' into main

b012a34

gsmith85 approved these changes Apr 10, 2026

View reviewed changes

gsmith85 reviewed Apr 10, 2026

View reviewed changes

amithanda added 4 commits April 11, 2026 09:08

docs: improve formatting and clarity in UCP core concepts documentation

38a4190

docs: minor fix to doc and line wrap

caeda15

docs: update terminology and clarify roles in UCP documentation

3b6cdb1

- Replaced "Client" with "Platform" and "Provider" with "Business" for consistency.

amithanda added the TC review Ready for TC review label Apr 16, 2026

igrigorik modified the milestones: 2026-04-08, Working Draft Apr 16, 2026

pjordan mentioned this pull request Apr 16, 2026

[Docs] Core Concepts Summary - Incorrect definition #294

Open

raginpirate reviewed Apr 22, 2026

View reviewed changes

	* Payment & Credential Providers: To securely hold sensitive user data and issue tokens or credentials on behalf of users, so that platforms and businesses never handle sensitive payment or identity information directly.
	* Payment & Credential Providers: To expose their services — tokenization, vaulting, credential issuance — once, and power secure commerce for users across any compatible platform and business.

Conversation

amithanda commented Apr 5, 2026

Description

Type of change

Checklist

Uh oh!

igrigorik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amithanda Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gsmith85 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amithanda Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gsmith85 Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amithanda commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

raginpirate left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

amithanda Apr 11, 2026 •

edited

Loading

amithanda Apr 11, 2026 •

edited

Loading

gsmith85 Apr 10, 2026 •

edited

Loading

amithanda commented Apr 11, 2026 •

edited

Loading