Schema 参考¶
本版使用 JSON Schema Draft 2020-12。下载完整 Schema，可在离线验证器中使用。$id 是草案的标识，不是下载地址；内部 $ref 不依赖网络。
下面的表由同一 Schema 在构建时生成，只列无条件必填项。条件必填由 Schema 的 allOf / oneOf 和相应规范章节共同解释，不手工维护另一份字段定义。
Catalog¶
| 字段 | 类型 / 值 | 无条件必填 | 说明 |
|---|---|---|---|
spec_version |
"0.2.1" |
是 | 精确的 AXI 表示版本 |
kind |
"catalog" |
是 | 文档类型 |
provider_id |
string |
是 | 提供方稳定标识 |
catalog_revision |
string |
是 | 目录修订 |
capabilities |
array |
是 | 有界能力摘要集合 |
next_cursor |
null / string |
是 | 不透明继续游标；null 表示结束 |
extensions |
extensions |
否 | 带命名空间的可选扩展 |
目录条目的引用与动作合同需要进一步交叉检查，见能力发现。
Action¶
| 字段 | 类型 / 值 | 无条件必填 | 说明 |
|---|---|---|---|
spec_version |
"0.2.1" |
是 | 精确的 AXI 表示版本 |
kind |
"action" |
是 | 文档类型 |
name |
string |
是 | 命名空间内的动作名 |
purpose |
string |
是 | 业务用途及选择条件 |
contract_revision |
string |
是 | 精确动作合同修订 |
effect |
read, view, draft, submit, irreversible |
是 | 领域副作用分类 |
required_context |
array |
是 | 执行必需的输入上下文字段 |
input_schema |
object |
是 | 业务输入的 Draft 2020-12 Schema |
output_schema |
object |
是 | 输出的 Draft 2020-12 Schema |
authorization |
string |
是 | 最终授权与前置检查说明 |
idempotency |
组合类型 |
是 | 键、恢复入口与保留期合同 |
bindings |
array |
是 | 现有载体及目标映射 |
extensions |
extensions |
否 | 带命名空间的可选扩展 |
写动作的 idempotency.mode 必须是 required，包括键字段、恢复动作和正整数保留秒数。必要上下文与键必须确实出现在必填输入中。嵌入的业务 Schema 要再做元 Schema 检查，见执行。
Result¶
| 字段 | 类型 / 值 | 无条件必填 | 说明 |
|---|---|---|---|
spec_version |
"0.2.1" |
是 | 精确的 AXI 表示版本 |
kind |
"result" |
是 | 文档类型 |
action |
string |
是 | 此次结果对应的原动作 |
contract_revision |
string |
是 | 精确动作合同修订 |
status |
succeeded, pending, blocked, failed, partial, cancelled, unknown |
是 | 证据支持的当前状态 |
context |
context |
是 | 服务端验证的范围化上下文 |
operation |
operation |
否 | 原操作引用与固定输入摘要 |
data |
object |
否 | 领域结果与验证范围 |
error |
error |
否 | 稳定代码、原因和解决方向 |
extensions |
extensions |
否 | 带命名空间的可选扩展 |
blocked、failed、unknown 需要错误；succeeded、pending、partial、cancelled 需要业务数据；pending、unknown 需要原操作引用。unknown 固定使用 result_unknown 和恢复方向。写入其他非 blocked 状态也需要原操作引用，该条件依赖动作合同，由跨文档检查验证。
Context¶
| 字段 | 类型 / 值 | 无条件必填 | 说明 |
|---|---|---|---|
scope_id |
string |
是 | 服务端验证的隔离范围引用 |
resource_id |
string |
否 | 当前资源的完整标识 |
revision |
integer / string |
否 | 对象版本；客户端按不透明条件使用 |
范围引用由服务端检查，不能从该字段推导权限。上下文规范定义切换、消歧与陈旧响应处理。
Operation¶
| 字段 | 类型 / 值 | 无条件必填 | 说明 |
|---|---|---|---|
id |
string |
否 | 提供方操作标识 |
key |
string |
是 | 原始幂等键 |
input_digest |
string |
是 | 固定输入摘要；sha256 加 64 位小写十六进制 |
recover_action |
string |
是 | 原操作只读恢复动作 |
input_digest 固定为 sha256: 加 64 位小写十六进制。具体输入规范化由动作提供方公布，示例向量见示例。
Page¶
| 字段 | 类型 / 值 | 无条件必填 | 说明 |
|---|---|---|---|
spec_version |
"0.2.1" |
是 | 精确的 AXI 表示版本 |
kind |
"page" |
是 | 文档类型 |
context |
context |
是 | 服务端验证的范围化上下文 |
query_revision |
string |
是 | 绑定游标的查询标识或修订 |
items |
array |
是 | 本页可见的结果项 |
next_cursor |
null / string |
是 | 不透明继续游标；null 表示结束 |
snapshot |
snapshot |
是 | 一致性模式及可选快照修订 |
extensions |
extensions |
否 | 带命名空间的可选扩展 |
非空游标的空页仍可继续；consistent 快照另需快照修订。见分页。
Batch¶
| 字段 | 类型 / 值 | 无条件必填 | 说明 |
|---|---|---|---|
spec_version |
"0.2.1" |
是 | 精确的 AXI 表示版本 |
kind |
"batch" |
是 | 文档类型 |
context |
context |
是 | 服务端验证的范围化上下文 |
status |
succeeded, partial |
是 | 证据支持的当前状态 |
results |
array |
是 | 按唯一 item_id 返回的逐项回执 |
snapshot |
snapshot |
是 | 一致性模式及可选快照修订 |
extensions |
extensions |
否 | 带命名空间的可选扩展 |
唯一项标识、整体与逐项状态的一致性、只读白名单和获权范围需要行为及交叉验证，见批量读取。
验证器能力¶
uv run --no-project --with-requirements requirements-test.txt python scripts/validate-contracts.py
该命令固定校验本仓库的 Schema 与审批示例包，不是通用认证服务。它拒绝包外合同引用和联网解析；不会执行工具或访问生产资源。负例与事务测试见验证指南。