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---56# UCP Schema Authoring78## Before writing code910**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.1112Also fetch https://ucp.dev/specification/reference/ for the base type schemas you'll reference.1314## Conceptual Architecture1516### Schema Categories1718The official 6 schema categories are:1920| 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 |2829**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.3031### Extension Composition via `allOf`3233Extensions compose with their parent capability using JSON Schema `allOf`:3435```json36{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```5455### Namespace Governance5657- `dev.ucp.*` — Governed by ucp.dev (official standard)58- `com.example.*` — Governed by example.com (your organization)59- `com.shopify.*` — Governed by shopify.com6061Use your organization's reverse-domain name for custom extensions.6263### Schema Resolution Sequence64651. Discovery — fetch Business profile662. Negotiation — compute capability intersection673. Fetch base capability schema from `schema` URI684. Fetch extension schemas for negotiated extensions695. Compose via `allOf`706. Validate checkout data against composed schema7172### Implementation Guidance7374- Use **JSON Schema 2020-12** (`https://json-schema.org/draft/2020-12/schema`)75- Host your schemas at a stable, versioned URL76- Declare extensions in your `/.well-known/ucp` profile with the `extends` field77- Test schema composition with the UCP schema validator: https://github.com/Universal-Commerce-Protocol/ucp-schema78- Fetch existing UCP schemas as reference before authoring custom ones
OrcaQubits