Schema 编写指南
Schema 编写指南
概述
本指南记录了编写 UCP JSON Schema 的约定，包括必需的元数据字段和版本策略。
Schema 元数据字段
UCP Schema 使用标准 JSON Schema 字段和 UCP 特定元数据的组合：
| 字段 | 标准 | 用途 | 必需于 |
|---|---|---|---|
$schema | JSON Schema | 声明 JSON Schema 草案版本（应该使用 draft/2020-12） | 所有 schema |
$id | JSON Schema | Schema 的规范 URI 用于 $ref 解析 | 所有 schema |
title | JSON Schema | 人类可读的显示名称 | 所有 schema |
description | JSON Schema | Schema 用途和用法 | 所有 schema |
name | UCP | 反向域名能力标识符 | 仅能力 schema |
version | UCP | 能力版本（YYYY-MM-DD 格式） | 仅能力 schema |
自描述 Schema
能力 Schema 必须是自描述的。 当平台获取 schema 时，它应该能够准确确定它代表什么能力和版本，而无需交叉引用其他文档。
为什么自描述？
- 独立版本控制：能力 可以 独立版本控制。Schema 必须显式声明其版本。
- 验证：验证器可以交叉检查能力声明的
schemaURL 是否指向 schema，其嵌入的name/version与声明匹配。不匹配是在构建时捕获的编写错误。 - 开发者体验：阅读 schema 文件时，集成者可以立即看到它定义了什么能力，而无需反向工程
$idURL。 - 紧凑命名空间：
name字段提供了标准化的反向域名标识符（例如，dev.ucp.shopping.checkout），比完整的$idURL 更紧凑和语义化。
name 字段
name 字段使用反向域名表示法进行能力识别：
dev.ucp.shopping.checkout # UCP checkout capability
dev.ucp.shopping.fulfillment # UCP fulfillment extension
com.shopify.loyalty # Vendor capabilityversion 字段
version 字段使用基于日期的版本控制（YYYY-MM-DD）：
"version": "2026-01-11"Schema 类别
能力 Schema
定义协商的能力。这些出现在发现 profile 和响应中的 ucp.capabilities[] 数组中。
必须包括：$schema、$id、title、description、name、version
组件 Schema
定义在能力内嵌入但不是独立协商的数据结构。
必须包括：$schema、$id、title、description
不得包括：name、version
类型 Schema
由能力和组件 schema 引用的可重用类型定义。
必须包括：$schema、$id、title、description
不得包括：name、version
示例：能力 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": {
...
}
}