Schema Authoring Guide¶

This guide documents conventions for authoring UCP JSON schemas: metadata fields, the registry pattern, schema variants, and versioning.

Schema Metadata Fields¶

UCP schemas use standard JSON Schema fields plus UCP-specific metadata:

Field	Standard	Purpose	Required For
`$schema`	JSON Schema	Declares JSON Schema draft version (SHOULD use `draft/2020-12`)	All schemas
`$id`	JSON Schema	Schema's canonical URI for `$ref` resolution	All schemas
`title`	JSON Schema	Human-readable display name	All schemas
`description`	JSON Schema	Schema purpose and usage	All schemas
`name`	UCP	Reverse-domain identifier; doubles as registry key	Capabilities, services, handlers
`version`	UCP	Entity version (`YYYY-MM-DD` format)	Capabilities, services, payment handlers
`id`	UCP	Instance identifier for multiple configurations	Payment handlers only

Why Self-Describing?¶

Capability schemas must be self-describing: when a platform fetches a schema, it should determine exactly what capability and version it represents without cross-referencing other documents. This matters because:

Independent versioning: Capabilities may version independently. The schema must declare its version explicitly—you can't infer it from the URL.
Validation: Validators can cross-check that a capability declaration's schema URL points to a schema whose embedded name/version match the declaration. Mismatches are authoring errors caught at build time.
Developer experience: When reading a schema file, integrators immediately see what capability it defines without reverse-engineering the $id URL.
Compact namespace: The name field provides a standardized reverse-domain identifier (e.g., dev.ucp.shopping.checkout) that's more compact and semantic than the full $id URL.

Why Both `$id` and `name`?¶

Field	Role	Format
`$id`	JSON Schema primitive for `$ref` resolution and tooling	URI (required by spec)
`name`	Registry key and stable identifier	Reverse-domain

$id must be a valid URI per JSON Schema spec. name is the key used in registries (capabilities, services, payment_handlers) and the wire protocol identifier used in capability negotiation—decoupled from schema hosting so that schema URLs can change as infrastructure evolves.

The reverse-domain format provides namespace governance: domain owners control their namespace (dev.ucp.*, com.shopify.*), avoiding collisions between UCP and vendor entities. This stable identity layer allows trust and resolution mechanisms to evolve independently—future versions could adopt verifiable credentials, content-addressed schemas, or other verification methods without breaking capability negotiation.

Why `version` Uses Dates?¶

The version field uses date-based versioning (YYYY-MM-DD) to enable:

Capability negotiation: Platforms request specific versions they support
Breaking change management: New versions get new dates; old versions remain valid and resolvable
Independent lifecycles: Extensions can release on their own schedule

Schema Categories¶

UCP schemas fall into six categories based on their role in the protocol.

Capability Schemas¶

Define negotiated capabilities that appear in ucp.capabilities{} registries.

Top-level fields: $schema, $id, title, description, name, version
Variants: platform_schema, business_schema, response_schema

Examples: checkout.json, fulfillment.json, discount.json, order.json

Service Schemas¶

Define transport bindings that appear in ucp.services{} registries. Each transport (REST, MCP, A2A, Embedded) is a separate entry.

Top-level fields: $schema, $id, title, description, name, version
Variants: platform_schema, business_schema
Transport requirements (additional beyond the common base):
- Platform profile (platform_schema): REST/MCP/Embedded require schema (OpenAPI/OpenRPC URL). A2A has no additional requirements.
- Business profile (business_schema): REST/MCP/A2A require endpoint (Agent Card URL for A2A). Embedded has no additional requirements.

Payment Handler Schemas¶

Define payment handler configurations in ucp.payment_handlers{} registries.

Top-level fields: $schema, $id, title, description, name, version, available_instruments
Variants: platform_schema, business_schema, response_schema
Instance id: Required to distinguish multiple configurations of the same handler
available_instruments: Optional. Array of supported instrument types with type-specific constraints (e.g., brands for credit cards). When absent, the handler places no restrictions — it supports the full set of instrument types defined by its handler schema.

Examples: com.google.pay, dev.shopify.shop_pay, dev.ucp.processor_tokenizer

→ See Payment Handler Guide for detailed guidance on handler structure, config/instrument/credential schemas, and the full specification template.

Component Schemas¶

Data structures embedded within capabilities but not independently negotiated. Do not appear in registries.

Top-level fields: $schema, $id, title, description
Omit: name, version (not independently versioned)

Examples:

schemas/shopping/payment.json — Payment configuration (part of checkout)

Type Schemas¶

Reusable definitions referenced by other schemas. Do not appear in registries.

Top-level fields: $schema, $id, title, description
Omit: name, version

Examples: types/buyer.json, types/line_item.json, types/postal_address.json

Meta Schemas¶

Define protocol structure rather than entity payloads.

Top-level fields: $schema, $id, title, description
Omit: name, version

Examples: ucp.json (entity base), capability.json, service.json, payment_handler.json

The Registry Pattern¶

UCP organizes capabilities, services, and handlers in registries—objects keyed by name rather than arrays of objects with name fields.

{
  "capabilities": {
    "dev.ucp.shopping.checkout": [{"version": "draft"}],
    "dev.ucp.shopping.fulfillment": [{"version": "draft"}]
  },
  "services": {
    "dev.ucp.shopping": [
      {"version": "draft", "transport": "rest"},
      {"version": "draft", "transport": "mcp"}
    ]
  },
  "payment_handlers": {
    "com.google.pay": [{"id": "gpay_1234", "version": "draft", "available_instruments": [{"type": "google_pay_card"}]}]
  }
}

Registry Contexts¶

The same registry structure appears in three contexts with different field requirements:

Context	Location	Required Fields
Platform Profile	Advertised URI	`version`, `spec`, `schema`
Business Profile	`/.well-known/ucp`	`version`; may add `config`
API Responses	Checkout/order payloads	`version` (+ `id` for handlers)

The Entity Pattern¶

All capabilities, services, and handlers extend a common entity base schema:

Field	Type	Description
`version`	string	Entity version (`YYYY-MM-DD`) — always required
`spec`	URI	Human-readable specification
`schema`	URI	JSON Schema URL
`id`	string	Instance identifier (handlers only)
`config`	object	Entity-specific configuration

Schema Variants¶

Each entity type defines three variants for different contexts:

platform_schema — Full declarations for discovery

{
  "dev.ucp.shopping.fulfillment": [{
    "version": "draft",
    "spec": "https://ucp.dev/draft/specification/fulfillment",
    "schema": "https://ucp.dev/draft/schemas/shopping/fulfillment.json",
    "config": {
      "supports_multi_group": true
    }
  }]
}

business_schema — Business-specific overrides

{
  "dev.ucp.shopping.fulfillment": [{
    "version": "draft",
    "config": {
      "allows_multi_destination": {"shipping": true}
    }
  }]
}

response_schema — Minimal references in API responses

{
  "ucp": {
    "capabilities": {
      "dev.ucp.shopping.fulfillment": [{"version": "draft"}]
    }
  }
}

Define all three in your schema's $defs:

"$defs": {
  "platform_schema": {
    "allOf": [{"$ref": "../capability.json#/$defs/platform_schema"}]
  },
  "business_schema": {
    "allOf": [{"$ref": "../capability.json#/$defs/business_schema"}]
  },
  "response_schema": {
    "allOf": [{"$ref": "../capability.json#/$defs/response_schema"}]
  }
}

String Vocabularies vs Enums¶

Prefer open string vocabularies with documented well-known values over closed enum arrays. Enums are a one-way door: adding a new value is a breaking change for strict validators, and removing one breaks existing producers.

// PREFER: open vocabulary — extensible without schema changes
"type": {
  "type": "string",
  "description": "Media type. Well-known values: `image`, `video`, `model_3d`."
}

// AVOID: closed enum — adding `audio` requires a schema version bump
"type": {
  "type": "string",
  "enum": ["image", "video", "model_3d"]
}

Use enum only for provably closed sets where new values would represent a fundamental protocol change (e.g., checkout.status: open | completed | expired). If the set might grow as new use cases emerge, use an open string with well-known values documented in the description.

Versioning Strategy¶

UCP Capabilities (`dev.ucp.*`)¶

UCP-authored capabilities version with protocol releases by default. Individual capabilities may version independently when needed.

Vendor Capabilities (`com.{vendor}.*`)¶

Capabilities outside dev.ucp.* version fully independently:

{
  "name": "com.shopify.loyalty",
  "version": "2025-09-01",
  "spec": "https://shopify.dev/ucp/loyalty",
  "schema": "https://shopify.dev/ucp/schemas/loyalty.json"
}

Vendor schemas follow the same self-describing requirements.

Extensibility and Forward Compatibility¶

When designing schemas, you must account for how older clients will validate newer payloads. In serialization formats like Protobuf, adding a new field or enum value is generally a safe, forward-compatible change.

Because modern code generators (e.g. Quicktype) translate JSON Schemas into strictly typed classes (e.g., Go structs or Java Enums), certain schema constraints will cause deserialization errors on older clients as the protocol evolves. Avoiding such changes helps minimize the need to up-version the protocol.

Open Enumerations¶

If a field's list of values might expand in the future (e.g., adding a "refunded" status or a new payment method), do not use enum.

Instead, define a standard string, document the requirement to ignore unknown values in the description, and use examples to convey current expected values to code generators. Avoid complex "Open Set" validation patterns (e.g., combining anyOf with const), as they frequently confuse client-side code generators and make schemas difficult to read.

"cancellation_reason": {
  "type": "string",
  "description": "Reason for order cancellation. Clients MUST tolerate and ignore unknown values.",
  "examples": ["customer_requested", "inventory_shortage", "fraud_suspected"]
}

Closed Enumerations¶

Use strict enum or const only for permanently fixed domains or when unknown values are inherently unsupported. Reserve them for cases where adding a new value inherently requires integrators to update their code (e.g., protocol versions, strict type discriminators, or days of the week).

"status": {
  "type": "string",
  "enum": ["open", "completed", "expired"],
  "description": "Lifecycle state. This domain is strictly bounded; unknown states represent a breakdown in the state machine and MUST be rejected."
}

Open Objects (`additionalProperties`)¶

Marking an object as closed preemptively prevents any future non-breaking additions to the schema. In a distributed protocol, what would otherwise be a backward-compatible field addition (e.g., adding a "gift_message" field to an order) becomes a breaking change for any client validating against a closed schema.

By default, JSON Schema is open and ignores unknown properties. Authors should leave this keyword omitted except in rare circumstances: polymorphic discriminators (where strictness prevents oneOf validation ambiguity), security-critical payloads (where unknown fields may indicate tampering), or protocol envelopes (where strictness is useful to catch typos in core metadata like the ucp block).

Anti-Pattern (Prevents adding new fields without a reversion):

"totals": {
  "type": "object",
  "properties": {
    "subtotal": {"type": "integer"}
  },
  "additionalProperties": false
}

Property-Count Constraints (`minProperties` / `maxProperties`)¶

By default, UCP schemas do not set minProperties or maxProperties on object fields:

maxProperties — Limits are deferred to implementers. The protocol does not define caps because any specific limit requires judgment calls that inevitably run into exceptions. Implementers are encouraged to impose their own constraints and surface clear error feedback to support debugging and good behavior.
minProperties — Empty objects ({}) are well-formed and harmless. Implementers should accept and process them as a no-op.

Complete Example: Capability Schema¶

A capability schema defines both payload structure and declaration variants:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/draft/schemas/shopping/checkout.json",
  "name": "dev.ucp.shopping.checkout",
  "version": "draft",
  "title": "Checkout",
  "description": "Base checkout schema. Extensions compose via allOf.",

  "$defs": {
    "platform_schema": {
      "allOf": [{"$ref": "../capability.json#/$defs/platform_schema"}]
    },
    "business_schema": {
      "allOf": [{"$ref": "../capability.json#/$defs/business_schema"}]
    },
    "response_schema": {
      "allOf": [{"$ref": "../capability.json#/$defs/response_schema"}]
    }
  },

  "type": "object",
  "required": ["ucp", "id", "line_items", "status", "currency", "totals", "links"],
  "properties": {
    "ucp": {"$ref": "../ucp.json#/$defs/response_checkout_schema"},
    "id": {"type": "string", "description": "Checkout identifier"},
    "line_items": {"type": "array", "items": {"$ref": "types/line_item.json"}},
    "status": {"type": "string", "enum": ["open", "completed", "expired"]},
    "currency": {"type": "string", "pattern": "^[A-Z]{3}$"},
    "totals": {"$ref": "types/totals.json"},
    "links": {"$ref": "types/links.json"}
  }
}

Key points:

Top-level name and version make the schema self-describing
$defs variants enable validation in different contexts
Payload properties define the actual checkout response structure