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`:

```json
{
  "$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