From 83f12eea3f5842115257a08f9f2f2b628d007cc1 Mon Sep 17 00:00:00 2001 From: "damaz@google.com" Date: Tue, 19 May 2026 11:36:42 +0200 Subject: [PATCH 1/9] chore: Include schema and documentation development instructions in README.md for better discoverability --- README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/README.md b/README.md index 949a9abbb..038a6491a 100644 --- a/README.md +++ b/README.md @@ -118,6 +118,47 @@ We welcome community contributions to enhance and evolve UCP. * **Contribution Guide:** See our [CONTRIBUTING.md](https://github.com/Universal-Commerce-Protocol/.github/blob/main/CONTRIBUTING.md) for details on how to contribute. +### Schema Development + +Schemas live in `source/` and are published with `ucp_*` annotations intact. +Agents use [ucp-schema](https://github.com/universal-commerce-protocol/ucp-schema) + to resolve annotations for specific operations at runtime. +1. Ensure `ucp-schema` is installed: + ```bash + cargo install ucp-schema # from crates.io + cargo install --git https://github.com/universal-commerce-protocol/ucp-schema # from git + ``` +2. Make updates to JSON files in `source/` +3. Run `ucp-schema lint source/` to validate syntax and references +If you change any JSON schemas, you may need to regenerate SDK client libraries. +For example, to regenerate Python Pydantic models run +`bash sdk/python/generate_models.sh`. Our CI system runs +`scripts/ci_check_models.sh` to verify that models can be generated +successfully from the schemas. + +### Documentation Development + +This project uses [uv](https://docs.astral.sh/uv/) for Python dependency management. +1. Install Python dependencies: `uv sync` +2. Ensure `ucp-schema` is installed (see above) +3. Run the development server: `uv run mkdocs serve --watch source` +4. Open **** in your browser +5. Before submitting, run `uv run mkdocs build --strict` to check for warnings/errors + +Alternatively, you can use the local build script to build the full site including spec versions: +```bash +./scripts/build_local.sh +``` +This will build the site and start a local server. You can use the `--draft-only` flag to skip release branches and only build the current draft: +```bash +./scripts/build_local.sh --draft-only +``` +You can start the documenation server locally by running +```bash +python3 -m http.server 8000 -d "local_preview" +``` +The local version of the documentation website will then be available at **** + ## What's Next Take a look at [our roadmap on ucp.dev](https://ucp.dev/documentation/roadmap/). From afc8f6f56da3c906f65a832b66a021f49c5010a7 Mon Sep 17 00:00:00 2001 From: "damaz@google.com" Date: Tue, 19 May 2026 11:40:43 +0200 Subject: [PATCH 2/9] update instructions --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 038a6491a..550313b6f 100644 --- a/README.md +++ b/README.md @@ -124,17 +124,15 @@ Schemas live in `source/` and are published with `ucp_*` annotations intact. Agents use [ucp-schema](https://github.com/universal-commerce-protocol/ucp-schema) to resolve annotations for specific operations at runtime. 1. Ensure `ucp-schema` is installed: + ```bash cargo install ucp-schema # from crates.io cargo install --git https://github.com/universal-commerce-protocol/ucp-schema # from git ``` + 2. Make updates to JSON files in `source/` 3. Run `ucp-schema lint source/` to validate syntax and references -If you change any JSON schemas, you may need to regenerate SDK client libraries. -For example, to regenerate Python Pydantic models run -`bash sdk/python/generate_models.sh`. Our CI system runs -`scripts/ci_check_models.sh` to verify that models can be generated -successfully from the schemas. + ### Documentation Development From 3a7037c65db37de4d055cf230294548ffdcff3a0 Mon Sep 17 00:00:00 2001 From: "damaz@google.com" Date: Tue, 19 May 2026 11:42:25 +0200 Subject: [PATCH 3/9] better run command --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 550313b6f..e5a20ac65 100644 --- a/README.md +++ b/README.md @@ -131,8 +131,11 @@ Agents use [ucp-schema](https://github.com/universal-commerce-protocol/ucp-schem ``` 2. Make updates to JSON files in `source/` -3. Run `ucp-schema lint source/` to validate syntax and references - +3. Run + ```bash + ucp-schema lint source/ + ``` + to validate syntax and references ### Documentation Development From 81bfdf6fbc679f75c1c044074d795164db9e8e37 Mon Sep 17 00:00:00 2001 From: "damaz@google.com" Date: Tue, 19 May 2026 11:45:19 +0200 Subject: [PATCH 4/9] fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e5a20ac65..87acd0918 100644 --- a/README.md +++ b/README.md @@ -154,7 +154,7 @@ This will build the site and start a local server. You can use the `--draft-only ```bash ./scripts/build_local.sh --draft-only ``` -You can start the documenation server locally by running +You can start the documentation server locally by running ```bash python3 -m http.server 8000 -d "local_preview" ``` From 931e8c4a79f1e66e11f9fb05c63bbe89ef374e23 Mon Sep 17 00:00:00 2001 From: "damaz@google.com" Date: Tue, 19 May 2026 11:53:25 +0200 Subject: [PATCH 5/9] fix super-linter errors --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 87acd0918..1572e4295 100644 --- a/README.md +++ b/README.md @@ -123,6 +123,7 @@ We welcome community contributions to enhance and evolve UCP. Schemas live in `source/` and are published with `ucp_*` annotations intact. Agents use [ucp-schema](https://github.com/universal-commerce-protocol/ucp-schema) to resolve annotations for specific operations at runtime. + 1. Ensure `ucp-schema` is installed: ```bash @@ -132,14 +133,17 @@ Agents use [ucp-schema](https://github.com/universal-commerce-protocol/ucp-schem 2. Make updates to JSON files in `source/` 3. Run + ```bash ucp-schema lint source/ ``` + to validate syntax and references ### Documentation Development This project uses [uv](https://docs.astral.sh/uv/) for Python dependency management. + 1. Install Python dependencies: `uv sync` 2. Ensure `ucp-schema` is installed (see above) 3. Run the development server: `uv run mkdocs serve --watch source` @@ -147,19 +151,26 @@ This project uses [uv](https://docs.astral.sh/uv/) for Python dependency managem 5. Before submitting, run `uv run mkdocs build --strict` to check for warnings/errors Alternatively, you can use the local build script to build the full site including spec versions: + ```bash ./scripts/build_local.sh ``` + This will build the site and start a local server. You can use the `--draft-only` flag to skip release branches and only build the current draft: + ```bash ./scripts/build_local.sh --draft-only ``` + You can start the documentation server locally by running + ```bash python3 -m http.server 8000 -d "local_preview" ``` + The local version of the documentation website will then be available at **** + ## What's Next Take a look at [our roadmap on ucp.dev](https://ucp.dev/documentation/roadmap/). From 91637ff4ed01d06cd4fc500740845ec91be9dba1 Mon Sep 17 00:00:00 2001 From: "damaz@google.com" Date: Tue, 19 May 2026 11:56:40 +0200 Subject: [PATCH 6/9] super-linter issues --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 1572e4295..34dc66173 100644 --- a/README.md +++ b/README.md @@ -170,7 +170,6 @@ python3 -m http.server 8000 -d "local_preview" The local version of the documentation website will then be available at **** - ## What's Next Take a look at [our roadmap on ucp.dev](https://ucp.dev/documentation/roadmap/). From 7903ddac435fe2047ad47707260bedf2c25da9a4 Mon Sep 17 00:00:00 2001 From: "damaz@google.com" Date: Tue, 19 May 2026 16:28:04 +0200 Subject: [PATCH 7/9] line length fixed to 80 + single line command --- README.md | 148 +++++++++++++++++++++++++++--------------------------- 1 file changed, 75 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 34dc66173..f5852ffa2 100644 --- a/README.md +++ b/README.md @@ -41,11 +41,11 @@ ensuring secure and consistent commerce experiences across the web. With UCP, businesses can: -* **Declare** supported capabilities to enable autonomous discovery by - platforms. -* **Facilitate** secure checkout sessions, with or without human intervention. -* **Offer** personalized shopping experiences through standardized data - exchange. +- **Declare** supported capabilities to enable autonomous discovery by + platforms. +- **Facilitate** secure checkout sessions, with or without human intervention. +- **Offer** personalized shopping experiences through standardized data + exchange. ## Why UCP? @@ -53,76 +53,78 @@ As commerce becomes increasingly agentic and distributed, the ability for different systems to interoperate without custom, one-off integrations is vital. UCP aims to: -* **Standardize Interaction:** Provide a uniform way for platforms to interact - with businesses, regardless of the underlying backend. -* **Modularize Commerce:** Breakdown commerce into distinct **Capabilities** - (e.g., Checkout, Order) and **Extensions** (e.g., Discounts, - Fulfillment), allowing for flexible implementation. -* **Enable Agentic Commerce:** Designed from the ground up to support AI - agents acting on behalf of users to discover products, fill carts, and - complete purchases securely. -* **Enhance Security:** Support for advanced security patterns like AP2 - mandates and verifiable credentials. +- **Standardize Interaction:** Provide a uniform way for platforms to interact + with businesses, regardless of the underlying backend. +- **Modularize Commerce:** Breakdown commerce into distinct **Capabilities** + (e.g., Checkout, Order) and **Extensions** (e.g., Discounts, Fulfillment), + allowing for flexible implementation. +- **Enable Agentic Commerce:** Designed from the ground up to support AI agents + acting on behalf of users to discover products, fill carts, and complete + purchases securely. +- **Enhance Security:** Support for advanced security patterns like AP2 mandates + and verifiable credentials. ### Key Features -* **Composable Architecture:** UCP defines **Capabilities** (such as - "Checkout" or "Identity Linking") that businesses implement to enable easy - integration. On top of that, specific **Extensions** can be added to enhance - the consumer experience without bloating the capability definitions. -* **Dynamic Discovery:** Businesses declare their supported Capabilities in a - standardized profile, allowing platforms to autonomously discover and - configure themselves. -* **Transport Agnostic:** The protocol is designed to work across various - transports. Businesses can offer Capabilities via REST APIs, MCP (Model - Context Protocol), or A2A, depending on their infrastructure. -* **Built on Standards:** UCP leverages existing open standards for payments, - identity, and security wherever applicable, rather than reinventing the - wheel. -* **Developer Friendly:** A comprehensive set of SDKs and libraries - facilitates rapid development and integration. +- **Composable Architecture:** UCP defines **Capabilities** (such as "Checkout" + or "Identity Linking") that businesses implement to enable easy integration. + On top of that, specific **Extensions** can be added to enhance the consumer + experience without bloating the capability definitions. +- **Dynamic Discovery:** Businesses declare their supported Capabilities in a + standardized profile, allowing platforms to autonomously discover and + configure themselves. +- **Transport Agnostic:** The protocol is designed to work across various + transports. Businesses can offer Capabilities via REST APIs, MCP (Model + Context Protocol), or A2A, depending on their infrastructure. +- **Built on Standards:** UCP leverages existing open standards for payments, + identity, and security wherever applicable, rather than reinventing the wheel. +- **Developer Friendly:** A comprehensive set of SDKs and libraries facilitates + rapid development and integration. ## Key Capabilities The initial release focuses on the essential primitives for transacting: -* **Checkout:** Facilitates checkout sessions including cart management and - tax calculation, supporting flows with or without human intervention. -* **Identity Linking:** Enables platforms to obtain authorization to perform - actions on a user's behalf via OAuth 2.0. -* **Order:** Webhook-based updates for order lifecycle events (shipped, - delivered, returned). -* **Payment Token Exchange:** Protocols for PSPs and Credential Providers to - securely exchange payment tokens and credentials. +- **Checkout:** Facilitates checkout sessions including cart management and tax + calculation, supporting flows with or without human intervention. +- **Identity Linking:** Enables platforms to obtain authorization to perform + actions on a user's behalf via OAuth 2.0. +- **Order:** Webhook-based updates for order lifecycle events (shipped, + delivered, returned). +- **Payment Token Exchange:** Protocols for PSPs and Credential Providers to + securely exchange payment tokens and credentials. ## Getting Started -* 📚 **Explore the Documentation:** Visit [ucp.dev](https://ucp.dev) for a - complete overview, the full protocol specification, tutorials, and guides. -* 🎬 **Review our - [samples](https://github.com/Universal-Commerce-Protocol/samples)** for - implementation examples. -* 🛠️ **Use our - [SDKs](https://github.com/orgs/Universal-Commerce-Protocol/repositories)** - to start building your own integrations. -* 📝 **Check conformance** with our [conformance tests](https://github.com/Universal-Commerce-Protocol/conformance). +- 📚 **Explore the Documentation:** Visit [ucp.dev](https://ucp.dev) for a + complete overview, the full protocol specification, tutorials, and guides. +- 🎬 **Review our + [samples](https://github.com/Universal-Commerce-Protocol/samples)** for + implementation examples. +- 🛠️ **Use our + [SDKs](https://github.com/orgs/Universal-Commerce-Protocol/repositories)** to + start building your own integrations. +- 📝 **Check conformance** with our + [conformance tests](https://github.com/Universal-Commerce-Protocol/conformance). ## Contributing We welcome community contributions to enhance and evolve UCP. -* **Questions & Discussions:** Join our [GitHub - Discussions](https://github.com/Universal-Commerce-Protocol/ucp/discussions). -* **Issues & Feedback:** Report issues or suggest improvements via GitHub - Issues. -* **Contribution Guide:** See our [CONTRIBUTING.md](https://github.com/Universal-Commerce-Protocol/.github/blob/main/CONTRIBUTING.md) - for details on how to contribute. +- **Questions & Discussions:** Join our + [GitHub Discussions](https://github.com/Universal-Commerce-Protocol/ucp/discussions). +- **Issues & Feedback:** Report issues or suggest improvements via GitHub + Issues. +- **Contribution Guide:** See our + [CONTRIBUTING.md](https://github.com/Universal-Commerce-Protocol/.github/blob/main/CONTRIBUTING.md) + for details on how to contribute. ### Schema Development Schemas live in `source/` and are published with `ucp_*` annotations intact. -Agents use [ucp-schema](https://github.com/universal-commerce-protocol/ucp-schema) - to resolve annotations for specific operations at runtime. +Agents use +[ucp-schema](https://github.com/universal-commerce-protocol/ucp-schema) to +resolve annotations for specific operations at runtime. 1. Ensure `ucp-schema` is installed: @@ -131,32 +133,31 @@ Agents use [ucp-schema](https://github.com/universal-commerce-protocol/ucp-schem cargo install --git https://github.com/universal-commerce-protocol/ucp-schema # from git ``` -2. Make updates to JSON files in `source/` -3. Run +1. Make updates to JSON files in `source/` - ```bash - ucp-schema lint source/ - ``` - - to validate syntax and references +1. Run `ucp-schema lint source/` to validate syntax and references ### Documentation Development -This project uses [uv](https://docs.astral.sh/uv/) for Python dependency management. +This project uses [uv](https://docs.astral.sh/uv/) for Python dependency +management. 1. Install Python dependencies: `uv sync` -2. Ensure `ucp-schema` is installed (see above) -3. Run the development server: `uv run mkdocs serve --watch source` -4. Open **** in your browser -5. Before submitting, run `uv run mkdocs build --strict` to check for warnings/errors +1. Ensure `ucp-schema` is installed (see above) +1. Run the development server: `uv run mkdocs serve --watch source` +1. Open **** in your browser +1. Before submitting, run `uv run mkdocs build --strict` to check for + warnings/errors -Alternatively, you can use the local build script to build the full site including spec versions: +Alternatively, you can use the local build script to build the full site +including spec versions: ```bash ./scripts/build_local.sh ``` -This will build the site and start a local server. You can use the `--draft-only` flag to skip release branches and only build the current draft: +This will build the site and start a local server. You can use the +`--draft-only` flag to skip release branches and only build the current draft: ```bash ./scripts/build_local.sh --draft-only @@ -168,16 +169,17 @@ You can start the documentation server locally by running python3 -m http.server 8000 -d "local_preview" ``` -The local version of the documentation website will then be available at **** +The local version of the documentation website will then be available at +**** ## What's Next Take a look at [our roadmap on ucp.dev](https://ucp.dev/documentation/roadmap/). Future enhancements include: -* **New Verticals:** Applications beyond Shopping (e.g., Travel, Services). -* **Loyalty:** Standardized management of loyalty programs and rewards. -* **Personalization:** Enhanced signals for personalized product discovery. +- **New Verticals:** Applications beyond Shopping (e.g., Travel, Services). +- **Loyalty:** Standardized management of loyalty programs and rewards. +- **Personalization:** Enhanced signals for personalized product discovery. ## About From 0e5e42ee0db32c7156b59388701ade438a8e2784 Mon Sep 17 00:00:00 2001 From: "damaz@google.com" Date: Wed, 20 May 2026 10:30:50 +0200 Subject: [PATCH 8/9] clarify agents role and use of ucp-schema --- README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f5852ffa2..7234bbe13 100644 --- a/README.md +++ b/README.md @@ -122,9 +122,13 @@ We welcome community contributions to enhance and evolve UCP. ### Schema Development Schemas live in `source/` and are published with `ucp_*` annotations intact. -Agents use -[ucp-schema](https://github.com/universal-commerce-protocol/ucp-schema) to -resolve annotations for specific operations at runtime. +**Agents** (such as AI assistants or platforms participating +in the protocol) can use the +[ucp-schema](https://github.com/universal-commerce-protocol/ucp-schema) tool to +resolve these annotations at runtime. This enables them to generate +operation-specific schema variants (e.g., for 'create', 'update', or 'read' +operations) from the master schemas, ensuring they only process fields relevant +to the current action and direction (request vs. response). 1. Ensure `ucp-schema` is installed: From 1742a02a6619d9ede2544da7a3db27d7936e9576 Mon Sep 17 00:00:00 2001 From: "damaz@google.com" Date: Wed, 20 May 2026 14:43:47 +0200 Subject: [PATCH 9/9] add callout for other repo contribution --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 7234bbe13..58638a95d 100644 --- a/README.md +++ b/README.md @@ -118,6 +118,9 @@ We welcome community contributions to enhance and evolve UCP. - **Contribution Guide:** See our [CONTRIBUTING.md](https://github.com/Universal-Commerce-Protocol/.github/blob/main/CONTRIBUTING.md) for details on how to contribute. +- **Specific Repositories:** When contributing to SDKs, Samples, Conformance, + or other UCP repositories, please follow the developer instructions in the + README of those repositories. ### Schema Development