Documentation
Schema Authoring Guide

Schema Authoring Guide

Overview

This guide documents the conventions for authoring UCP JSON schemas, including required metadata fields and versioning strategy.

Schema Metadata Fields

UCP schemas use a combination of standard JSON Schema fields and UCP-specific metadata:

FieldStandardPurposeRequired For
$schemaJSON SchemaDeclares JSON Schema draft version (SHOULD use draft/2020-12)All schemas
$idJSON SchemaSchema’s canonical URI for $ref resolutionAll schemas
titleJSON SchemaHuman-readable display nameAll schemas
descriptionJSON SchemaSchema purpose and usageAll schemas
nameUCPReverse-domain capability identifierCapability schemas only
versionUCPCapability version (YYYY-MM-DD format)Capability schemas only

Self-Describing Schemas

Capability schemas MUST be self-describing. When a platform fetches a schema, it should be able to determine exactly what capability and version it represents without cross-referencing other documents.

Why self-describing?

  1. Independent versioning: Capabilities MAY version independently
  2. Validation: Validators can cross-check that capability declarations match
  3. Developer experience: Integrators immediately see what capability the schema defines
  4. Compact namespace: The name field provides a standardized reverse-domain identifier

The name Field

The name field uses reverse-domain notation for capability identification:

dev.ucp.shopping.checkout        # UCP checkout capability
dev.ucp.shopping.fulfillment     # UCP fulfillment extension
com.shopify.loyalty              # Vendor capability

The version Field

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

"version": "2026-01-11"

Schema Categories

Capability Schemas

Schemas that define negotiated capabilities. These appear in ucp.capabilities[] arrays.

MUST include: $schema, $id, title, description, name, version

Component Schemas

Schemas that define data structures embedded within capabilities but are not independently negotiated.

MUST include: $schema, $id, title, description MUST NOT include: name, version

Type Schemas

Reusable type definitions referenced by capability and component schemas.

MUST include: $schema, $id, title, description MUST NOT include: name, version

Example: Capability Schema 

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ucp.dev/schemas/shopping/checkout.json",
  "name": "dev.ucp.shopping.checkout",
  "version": "2026-01-11",
  "title": "Checkout",
  "description": "Base checkout schema. Extensions compose via allOf.",
  "type": "object",
  "required": ["ucp", "id", "line_items", "status", "currency"],
  "properties": {
    ...
  }
}
RoadmapUCP Overview