From d5f29e6e3ffb3f9ffed1d3f7af6ac814115ac24c Mon Sep 17 00:00:00 2001 From: omsaisudarshan108 Date: Mon, 12 Jan 2026 03:40:42 -0500 Subject: [PATCH] docs: add discovery validation rules and agent checkout flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR focuses on documentation improvements: 1. Profile Validation Rules: Adds clear validation requirements for discovery profiles including version format, service requirements, endpoint format, and capability reference constraints. 2. Agent Checkout Reference Flow: Documents the canonical REST checkout sequence with a Mermaid diagram and minimal payload examples showing the create → update → complete flow. 3. Developer Tooling: Adds regenerate_artifacts.sh script to simplify the workflow for regenerating schemas and SDK models in one command. The discovery profile example now only includes UCP-governed capabilities (checkout, fulfillment, discount) following governance guidelines. Co-Authored-By: Claude Sonnet 4.5 --- CONTRIBUTING.md | 3 ++ docs/specification/checkout-rest.md | 50 ++++++++++++++++++++++++++++- docs/specification/overview.md | 15 ++++++++- scripts/regenerate_artifacts.sh | 17 ++++++++++ 4 files changed, 83 insertions(+), 2 deletions(-) create mode 100755 scripts/regenerate_artifacts.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d250e125..a566b1f36 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -130,6 +130,9 @@ 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. +If you want a single command that regenerates schemas and SDK artifacts, run +`bash scripts/regenerate_artifacts.sh`. + It is also important to go through documentation locally whenever spec files are updated to ensure there are no broken references or stale/missing contents. diff --git a/docs/specification/checkout-rest.md b/docs/specification/checkout-rest.md index 38cff117b..aae7df681 100644 --- a/docs/specification/checkout-rest.md +++ b/docs/specification/checkout-rest.md @@ -49,6 +49,54 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version | [Complete Checkout](checkout.md#complete-checkout) | `POST` | `/checkout-sessions/{id}/complete` | Place the order. | | [Cancel Checkout](checkout.md#cancel-checkout) | `POST` | `/checkout-sessions/{id}/cancel` | Cancel a checkout session. | +## Agent Checkout Reference Flow + +This sequence shows a canonical REST flow for an agent completing checkout. + +```mermaid +sequenceDiagram + participant Platform + participant Business + Platform->>Business: POST /checkout-sessions (create checkout) + Business-->>Platform: 201 checkout (status=incomplete) + Platform->>Business: PUT /checkout-sessions/{id} (add buyer/fulfillment) + Business-->>Platform: 200 checkout (status=ready_for_complete) + Platform->>Business: POST /checkout-sessions/{id}/complete + Business-->>Platform: 200 checkout (status=completed, order) +``` + +### Minimal Payloads + +**Create checkout (request)** + +```json +{ + "line_items": [ + { + "item": { "id": "item_123", "title": "Red T-Shirt", "price": 2500 }, + "quantity": 1 + } + ] +} +``` + +**Complete checkout (request)** + +```json +{ + "id": "chk_1234567890", + "payment": { + "handlers": [ + { + "id": "business_tokenizer", + "type": "token", + "credential": { "token": "tok_visa_123" } + } + ] + } +} +``` + ## Examples ### Create Checkout @@ -1346,4 +1394,4 @@ authentication is required, the REST transport **MAY** use: 4. **Mutual TLS**: For high-security environments. Businesses **MAY** require authentication for some operations while leaving -others open (e.g., public checkout without authentication). \ No newline at end of file +others open (e.g., public checkout without authentication). diff --git a/docs/specification/overview.md b/docs/specification/overview.md index 803784b95..891c7ae73 100644 --- a/docs/specification/overview.md +++ b/docs/specification/overview.md @@ -330,6 +330,19 @@ capabilities. Payment configuration is a sibling—see contains public keys (JWK format) used to verify signatures on webhooks and other authenticated messages from the business. +#### Profile Validation Rules + +Profiles **MUST** conform to the discovery schema and follow these rules: + +- `ucp.version` **MUST** be a valid `YYYY-MM-DD` version string. +- `ucp.services` **MUST** include a `dev.ucp.shopping` entry for Shopping use + cases. +- Service `endpoint` values **MUST NOT** include a trailing slash. +- If `rest` is present, both `schema` and `endpoint` **MUST** be provided. +- Capability `spec` and `schema` URLs **MUST** be absolute and HTTPS. +- Capabilities that declare `extends` **MUST** reference a capability present + in the same profile. + #### Platform Profile Platform profiles are similar and include signing keys for capabilities @@ -1168,4 +1181,4 @@ Vendors control their own release schedules and versioning strategy. | **Payment Service Provider** | PSP | The financial infrastructure provider that processes payments, authorizations, and settlements on behalf of the business. | | **Platform** | - | The consumer-facing surface (AI agent, app, website) acting on behalf of the user to discover businesses and facilitate commerce. | | **Verifiable Digital Credential** | VDC | An Issuer-signed credential (set of claims) whose authenticity can be verified cryptographically. Used in UCP for secure payment authorizations. | -| **Verifiable Presentation** | VP | A presentation of one or more VDCs that includes a cryptographic proof of binding, used to prove authorization to a business or PSP. | \ No newline at end of file +| **Verifiable Presentation** | VP | A presentation of one or more VDCs that includes a cryptographic proof of binding, used to prove authorization to a business or PSP. | diff --git a/scripts/regenerate_artifacts.sh b/scripts/regenerate_artifacts.sh new file mode 100755 index 000000000..960cc31aa --- /dev/null +++ b/scripts/regenerate_artifacts.sh @@ -0,0 +1,17 @@ +#!/bin/bash +# Regenerates spec outputs and SDK models in one command. + +set -e + +ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)" + +cd "$ROOT_DIR" + +python generate_schemas.py + +SDK_SCRIPT="$ROOT_DIR/sdk/python/generate_models.sh" +if [ -f "$SDK_SCRIPT" ]; then + bash "$SDK_SCRIPT" +else + echo "SDK generator not found at $SDK_SCRIPT. Skipping SDK regeneration." +fi