Schema Reference
Schema Reference
Section titled “Schema Reference”This page provides a reference for all the capability data models and types used within the UCP.
Capability Schemas
Section titled “Capability Schemas”Capability schemas define negotiated capabilities that appear in ucp.capabilities{} registries.
Each capability schema is self-describing with name and version fields.
Key capabilities:
| Capability | Name | Description |
|---|---|---|
| Checkout | dev.ucp.shopping.checkout | Core checkout session management |
| Cart | dev.ucp.shopping.cart | Shopping cart before checkout |
| Catalog Search | dev.ucp.shopping.catalog.search | Product search |
| Catalog Lookup | dev.ucp.shopping.catalog.lookup | Product lookup by ID |
| Order | dev.ucp.shopping.order | Post-checkout order management |
| Identity Linking | dev.ucp.common.identity_linking | OAuth 2.0 account linking |
Type Schemas
Section titled “Type Schemas”Type schemas define reusable data structures referenced by other schemas.
They do not appear in registries and do not have name or version fields.
Key types:
| Type | Description |
|---|---|
types/buyer.json | Buyer information |
types/line_item.json | Order/cart line item |
types/postal_address.json | Physical address |
types/payment_instrument.json | Base payment instrument |
types/card_payment_instrument.json | Card-based instrument |
types/payment_credential.json | Base credential type |
types/token_credential.json | Token credential |
types/payment_identity.json | Payment participant identity |
types/binding.json | Credential binding context |
Selected Payment Instrument
Section titled “Selected Payment Instrument”The selected_payment_instrument type extends the base payment_instrument
with a selected boolean field indicating which instrument was chosen for checkout.
Pagination Request
Section titled “Pagination Request”| Field | Type | Description |
|---|---|---|
limit | integer | Maximum number of results |
cursor | string | Cursor for next page (optional) |
Pagination Response
Section titled “Pagination Response”| Field | Type | Description |
|---|---|---|
cursor | string | Cursor for next page request |
has_next_page | boolean | Whether more results are available |
total_count | integer | Total number of results (if available) |
Error Code
Section titled “Error Code”UCP uses a consistent error object format:
| Field | Type | Description |
|---|---|---|
code | string | Machine-readable error code |
content | string | Human-readable error message |
Extension Schemas
Section titled “Extension Schemas”Extensions compose with capabilities via allOf. Key extensions:
| Extension | Name | Description |
|---|---|---|
| Fulfillment | dev.ucp.shopping.fulfillment | Shipping/pickup methods |
| Discount | dev.ucp.shopping.discount | Discount codes and allocations |
| AP2 Mandates | dev.ucp.shopping.ap2_mandates | Cryptographic payment authorization |
| Buyer Consent | dev.ucp.shopping.buyer_consent | GDPR/CCPA consent management |
UCP Metadata
Section titled “UCP Metadata”The following schemas define the structure of UCP metadata used in discovery and responses.
Platform Discovery Profile
Section titled “Platform Discovery Profile”The top-level structure of a platform profile document (hosted at a URI advertised by the platform).
| Field | Description |
|---|---|
ucp.version | Protocol version (YYYY-MM-DD) |
ucp.capabilities | Map of capability names to capability declarations |
ucp.services | Map of service names to transport bindings |
ucp.payment_handlers | Map of handler names to handler declarations |
signing_keys | Array of JWK public keys for signature verification |
Business Discovery Profile
Section titled “Business Discovery Profile”The top-level structure of a business discovery document (/.well-known/ucp).
Same structure as platform profile. Hosted at /.well-known/ucp on the business domain.
Checkout Response Metadata
Section titled “Checkout Response Metadata”The ucp object included in checkout responses:
| Field | Description |
|---|---|
version | Protocol version used in this response |
capabilities | Map of active capability names to their versions |
payment_handlers | Resolved payment handler configurations |
Cart Response Metadata
Section titled “Cart Response Metadata”The ucp object included in cart responses:
| Field | Description |
|---|---|
version | Protocol version used in this response |
capabilities | Map of active capability names to their versions |
Order Response Metadata
Section titled “Order Response Metadata”The ucp object included in order responses or events:
| Field | Description |
|---|---|
version | Protocol version used in this response |
capabilities | Map of active capability names to their versions |
Capability
Section titled “Capability”This object describes a single capability or extension. It appears in the
capabilities map in discovery profiles and responses.
Capability (Discovery)
Section titled “Capability (Discovery)”As seen in discovery profiles (platform or business):
| Field | Type | Required | Description |
|---|---|---|---|
version | string | Yes | Capability version (YYYY-MM-DD) |
spec | string | No | URL to the capability specification |
schema | string | No | URL to the capability JSON schema |
config | object | No | Capability-specific configuration |
Capability (Response)
Section titled “Capability (Response)”As seen in response messages:
| Field | Type | Required | Description |
|---|---|---|---|
version | string | Yes | Capability version (YYYY-MM-DD) |