UCP Protocol Architecture

Overview

Universal Commerce Protocol (UCP) is an open standard for commerce interoperability. It enables AI agents and applications to interact with e-commerce systems through a unified API specification.

Protocol Layers

┌─────────────────────────────────────────┐
│           Generated Specs               │
│  (OpenAPI 3.1.0 + OpenRPC 1.3.2)       │
├─────────────────────────────────────────┤
│           Source Schemas                │
│      (JSON Schema Draft 2020-12)        │
├─────────────────────────────────────────┤
│          Type Definitions               │
│      (Reusable Commerce Types)          │
└─────────────────────────────────────────┘

Directory Structure

ucp/
├── source/
│   └── schemas/
│       └── shopping/           # Source JSON schemas
│           ├── checkout.json
│           ├── order.json
│           ├── payment.json
│           ├── product.json
│           ├── cart.json
│           ├── customer.json
│           ├── fulfillment.json
│           └── types/          # Reusable types
├── generated/
│   ├── openapi/               # OpenAPI 3.1.0 specs
│   │   └── shopping.openapi.json
│   ├── openrpc/               # OpenRPC 1.3.2 specs
│   │   └── shopping.openrpc.json
│   └── json-schema/           # Bundled schemas
│       └── shopping.schema.json
├── scripts/
│   ├── generate_schemas.py    # Main generation script
│   ├── validate_specs.py      # Validation script
│   └── generate_ts_schema_types.js
└── docs/                      # Documentation

Method Naming Convention

UCP methods follow dot notation: domain.capability.action

Examples:

• shopping.cart.create - Create a cart
• shopping.cart.add_item - Add item to cart
• shopping.checkout.initiate - Start checkout
• shopping.order.get - Get order details
• shopping.product.search - Search products

Generation Pipeline

Source schemas are processed to generate:

1. OpenAPI 3.1.0 - REST API specification
2. OpenRPC 1.3.2 - JSON-RPC specification
3. Bundled JSON Schema - Dereferenced schemas
4. TypeScript Types - Type definitions

Running Generation

# Generate all specs
python scripts/generate_schemas.py

# Generate TypeScript types
node scripts/generate_ts_schema_types.js

Validation Pipeline

Validation ensures schema correctness:

# Validate all specs
python scripts/validate_specs.py

Validation checks:

• JSON Schema syntax valid
• All $ref references resolve
• UCP annotations present
• Method names follow convention
• Required fields defined

Capability Design Process

To add a new capability:

1. Design types - Create reusable types in types/
2. Define schemas - Create capability schema with request/response
3. Add annotations - Apply ucp_request/ucp_response
4. Validate - Run validate_specs.py
5. Generate - Run generate_schemas.py
6. Review - Check generated OpenAPI/OpenRPC

Core vs Capability Schemas

Core schemas (ucp_core: true):

• Protocol-level fields
• Error handling
• Pagination
• Common metadata

Capability schemas:

• Domain-specific operations
• Business logic
• Commerce entities

Additional Resources

Reference Files

For detailed architecture documentation:

• references/openapi-patterns.md - OpenAPI generation patterns
• references/openrpc-patterns.md - OpenRPC generation patterns

Examples

• examples/full-capability-flow.md - End-to-end capability creation
• examples/method-naming.md - Method naming examples