UCP Schema Authoring
Before writing code
Fetch live spec: Web-search site:ucp.dev documentation schema-authoring and fetch the page for the exact schema metadata requirements, category rules, and composition patterns.
Also fetch https://ucp.dev/specification/reference/ for the base type schemas you'll reference.
Conceptual Architecture
Schema Categories
The official 6 schema categories are:
| Category |
Required Metadata |
Purpose |
Examples |
| Capability |
$schema, $id, title, description, name, version |
Major functional domain |
checkout, order, identity_linking |
| Service |
$schema, $id, title, description |
Transport binding definition |
REST, MCP, A2A |
| Payment Handler |
$schema, $id, title, description |
Payment method specification |
Google Pay, Shop Pay |
| Component |
$schema, $id, title, description |
Reusable structural unit |
payment, payment_data |
| Type |
$schema, $id, title, description |
Primitive data model |
buyer, line_item, postal_address, total |
| Meta |
$schema, $id, title, description |
Schema about schemas |
ucp.json, capability.json |
Note on Extensions: Extensions (e.g., fulfillment, discount, buyer_consent, ap2_mandate) are NOT a separate top-level category. They are Capabilities with an extends field that references their parent capability. An extension has the same required metadata as a Capability ($schema, $id, title, description, name, version) plus the extends field.
Extension Composition via allOf
Extensions compose with their parent capability using JSON Schema allOf:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/my-extension.json",
"title": "My Extension",
"description": "Adds X to checkout",
"name": "com.example.my_extension",
"version": "2026-01-11",
"extends": "dev.ucp.shopping.checkout",
"allOf": [
{ "$ref": "https://ucp.dev/schemas/shopping/checkout.json" },
{
"properties": {
"my_field": { "type": "object" }
}
}
]
}
Namespace Governance
dev.ucp.* — Governed by ucp.dev (official standard)com.example.* — Governed by example.com (your organization)com.shopify.* — Governed by shopify.com
Use your organization's reverse-domain name for custom extensions.
Schema Resolution Sequence
- Discovery — fetch Business profile
- Negotiation — compute capability intersection
- Fetch base capability schema from
schema URI
- Fetch extension schemas for negotiated extensions
- Compose via
allOf
- Validate checkout data against composed schema
Implementation Guidance
- Use JSON Schema 2020-12 (
https://json-schema.org/draft/2020-12/schema)
- Host your schemas at a stable, versioned URL
- Declare extensions in your
/.well-known/ucp profile with the extends field
- Test schema composition with the UCP schema validator: https://github.com/Universal-Commerce-Protocol/ucp-schema
- Fetch existing UCP schemas as reference before authoring custom ones
1---2name: ucp-schema-authoring3description: Author custom UCP schemas and extensions — create capability schemas, extension schemas, and type definitions using JSON Schema 2020-12 composition. Use when extending UCP with custom capabilities or building domain-specific extensions.4---5
6# UCP Schema Authoring
7
8## Before writing code
9
10**Fetch live spec**: Web-search `site:ucp.dev documentation schema-authoring` and fetch the page for the exact schema metadata requirements, category rules, and composition patterns.
11
12Also fetch https://ucp.dev/specification/reference/ for the base type schemas you'll reference.
13
14## Conceptual Architecture
15
16### Schema Categories
17
18The official 6 schema categories are:
19
20| Category | Required Metadata | Purpose | Examples |
21|----------|-------------------|---------|----------|
22| **Capability** | `$schema`, `$id`, `title`, `description`, `name`, `version` | Major functional domain | checkout, order, identity_linking |
23| **Service** | `$schema`, `$id`, `title`, `description` | Transport binding definition | REST, MCP, A2A |
24| **Payment Handler** | `$schema`, `$id`, `title`, `description` | Payment method specification | Google Pay, Shop Pay |
25| **Component** | `$schema`, `$id`, `title`, `description` | Reusable structural unit | payment, payment_data |
26| **Type** | `$schema`, `$id`, `title`, `description` | Primitive data model | buyer, line_item, postal_address, total |
27| **Meta** | `$schema`, `$id`, `title`, `description` | Schema about schemas | ucp.json, capability.json |
28
29**Note on Extensions**: Extensions (e.g., fulfillment, discount, buyer_consent, ap2_mandate) are NOT a separate top-level category. They are **Capabilities with an `extends` field** that references their parent capability. An extension has the same required metadata as a Capability (`$schema`, `$id`, `title`, `description`, `name`, `version`) plus the `extends` field.
30
31### Extension Composition via `allOf`
32
33Extensions compose with their parent capability using JSON Schema `allOf`:
34
35```json
36{
37 "$schema": "https://json-schema.org/draft/2020-12/schema",
38 "$id": "https://example.com/schemas/my-extension.json",
39 "title": "My Extension",
40 "description": "Adds X to checkout",
41 "name": "com.example.my_extension",
42 "version": "2026-01-11",
43 "extends": "dev.ucp.shopping.checkout",
44 "allOf": [
45 { "$ref": "https://ucp.dev/schemas/shopping/checkout.json" },
46 {
47 "properties": {
48 "my_field": { "type": "object" }
49 }
50 }
51 ]
52}
53```
54
55### Namespace Governance
56
57- `dev.ucp.*` — Governed by ucp.dev (official standard)
58- `com.example.*` — Governed by example.com (your organization)
59- `com.shopify.*` — Governed by shopify.com
60
61Use your organization's reverse-domain name for custom extensions.
62
63### Schema Resolution Sequence
64
651. Discovery — fetch Business profile
662. Negotiation — compute capability intersection
673. Fetch base capability schema from `schema` URI
684. Fetch extension schemas for negotiated extensions
695. Compose via `allOf`
706. Validate checkout data against composed schema
71
72### Implementation Guidance
73
74- Use **JSON Schema 2020-12** (`https://json-schema.org/draft/2020-12/schema`)
75- Host your schemas at a stable, versioned URL
76- Declare extensions in your `/.well-known/ucp` profile with the `extends` field
77- Test schema composition with the UCP schema validator: https://github.com/Universal-Commerce-Protocol/ucp-schema
78- Fetch existing UCP schemas as reference before authoring custom ones
majiayu000