diff --git a/README.md b/README.md index 949a9abb..58638a95 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,79 +53,140 @@ 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. +- **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 + +Schemas live in `source/` and are published with `ucp_*` annotations intact. +**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: + + ```bash + cargo install ucp-schema # from crates.io + cargo install --git https://github.com/universal-commerce-protocol/ucp-schema # from git + ``` + +1. Make updates to JSON files in `source/` + +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. + +1. Install Python dependencies: `uv sync` +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: + +```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/). 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