ucp-schema-authoring

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

1. Discovery — fetch Business profile
2. Negotiation — compute capability intersection
3. Fetch base capability schema from schema URI
4. Fetch extension schemas for negotiated extensions
5. Compose via allOf
6. 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