Specification Overview

Version Information

• Protocol Version: 2026-01-11
• This document based on: Official specification/overview.md

Keywords Notice

The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, OPTIONAL in this specification are to be interpreted as described in RFC 2119 and RFC 8174.

Namespace Governance

UCP uses reverse domain encoding for governance authority:

Naming Format

{reverse-domain}.{service}.{capability}

Authority Mapping

Validation Requirement: Platforms MUST verify that the capability spec URL origin matches the namespace authority.

Naming Examples

Service (Service) Definition

Service defines the API surface and transport bindings:

Endpoint Resolution Rules

OpenAPI paths are appended directly to the endpoint:

endpoint: https://business.example.com/ucp/v1
path: /checkout-sessions
result: POST https://business.example.com/ucp/v1/checkout-sessions

Capability Definition

Capability is a functional feature within a Service:

Extension Definition

Extension is an optional capability enhancement module:

{
  "name": "dev.ucp.shopping.fulfillment",
  "version": "2026-01-11",
  "spec": "https://ucp.dev/specification/fulfillment",
  "schema": "https://ucp.dev/schemas/shopping/fulfillment.json",
  "extends": "dev.ucp.shopping.checkout"
}

Profile Structure

Business Profile

Published at https://business.example.com/.well-known/ucp:

{
  "ucp": {
    "version": "2026-01-11",
    "services": {
      "dev.ucp.shopping": {
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/overview",
        "rest": {
          "schema": "https://ucp.dev/services/shopping/rest.openapi.json",
          "endpoint": "https://business.example.com/ucp/v1"
        }
      }
    },
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/checkout",
        "schema": "https://ucp.dev/schemas/shopping/checkout.json"
      },
      {
        "name": "dev.ucp.shopping.fulfillment",
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/fulfillment",
        "schema": "https://ucp.dev/schemas/shopping/fulfillment.json",
        "extends": "dev.ucp.shopping.checkout"
      }
    ]
  },
  "payment": {
    "handlers": [...]
  },
  "signing_keys": [...]
}

Platform Profile

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [...]
  },
  "payment": {
    "handlers": [...]
  },
  "signing_keys": [...]
}

Platform Declaration Mechanism

HTTP Transport

Use UCP-Agent header (Dictionary Structured Field syntax):

UCP-Agent: profile="https://agent.example/profiles/shopping-agent.json"

MCP Transport

Use _meta.ucp field:

{
  "jsonrpc": "2.0",
  "method": "create_checkout",
  "params": {
    "_meta": {
      "ucp": {
        "profile": "https://agent.example/profiles/shopping-agent.json"
      }
    },
    "line_items": [...]
  },
  "id": 1
}

Capability Negotiation Protocol

Platform Requirements

1. Profile Declaration: Include Profile URI in each request
2. Discovery: Pre-fetch and cache Business Profile
3. Namespace Validation: Verify spec URL origin matches namespace authority
4. Schema Resolution: Fetch and compose schemas for negotiated capabilities

Business Requirements

1. Profile Resolution: Fetch and validate platform Profile URI when receiving requests with one
2. Capability Intersection: Calculate intersection of platform and business capabilities
3. Extension Validation: Remove extensions whose parent capability is not in the intersection
4. Response Requirements: Include ucp field in each response (version and capabilities)

Capability Intersection Algorithm

Input: Platform capability list, Business capability list
Output: Active capability list

Steps:
1. Calculate intersection: Keep capabilities with matching names
2. Prune orphaned extensions: Remove extensions whose parent capability is not in the intersection
3. Repeat step 2 until no capabilities are removed

Capability Declaration in Response

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {"name": "dev.ucp.shopping.checkout", "version": "2026-01-11"},
      {"name": "dev.ucp.shopping.fulfillment", "version": "2026-01-11"}
    ]
  },
  "id": "checkout_123",
  "line_items": [...]
}

Error Handling

When negotiation fails, the business MUST return an error response:

{
  "status": "requires_escalation",
  "messages": [{
    "type": "error",
    "code": "version_unsupported",
    "message": "Version 2026-01-11 is not supported.",
    "severity": "requires_buyer_input"
  }]
}

Payment Architecture Overview

Trust Model

Payment Lifecycle

1. Negotiate → Business advertises handlers
2. Acquire → Platform executes handler logic
3. Complete → Platform submits opaque credential

Transport Protocols

UCP supports the following transport protocols:

REST Requirements

• Content-Type: application/json
• Methods: Standard HTTP verbs (POST, GET, etc.)
• Status Codes: Standard HTTP status codes

Standard Capabilities

Security and Authentication

Transport Security

All UCP communication MUST use HTTPS.

Request Authentication

• Platform → Business: SHOULD use standard headers (e.g., Authorization: Bearer <token>)
• Business → Platform (Webhook): MUST use signature verification

Data Privacy

Sensitive data MUST comply with PCI-DSS and GDPR requirements.

Transaction Integrity

For scenarios requiring cryptographic proof, UCP supports the AP2 Mandates Extension, providing:

• Business cryptographic signatures of checkout terms
• Platform cryptographic proof of user authorization

Version Control

Version Format

Use date-based versioning: YYYY-MM-DD

Version Negotiation

IF platform version ≤ business version:
    Business MUST handle the request
ELSE:
    Business MUST return version_unsupported error

Backward Compatibility

Compatible Changes (no new version needed):

• Adding optional fields
• Adding optional parameters
• Adding new endpoints

Breaking Changes (require new version):

• Removing or renaming fields
• Changing field types
• Making optional fields required

Independent Component Versions

• UCP protocol is independent of capability versions
• Each capability has independent version control
• Transport protocols may define their own version handling

Reference Links

• Official Specification Overview
• GitHub Repository
• Schema Reference