06 JSON Schema 要求

目的

本章定义规范性机器可读工件的 Schema 级要求。

范围

至少在 v0.1 中，应为以下核心规范性工件提供稳定的 Schema 定义：

• manifest.json
• devicespec.json
• calset.json
• pulseir.json
• runresult.json

参考草案还给出了 UQCI Program Core Schema，用于强调 canonical 模型独立于 OpenQASM。即使完整 Schema 文本不全部放入本章，这一原则也应继续指导仓库中的 Schema 设计。

一般要求

所有规范性 Schema 都应当：

• 显式声明 JSON Schema draft 版本
• 使用稳定的顶层标题与标识符
• 清晰区分必填字段与可选字段
• 避免通过意外 extra properties 引入失控扩展
• 与 canonical typed model 保持一致

各工件的结构预期

参考草案分别给出了 manifest.json、devicespec.json 与 calset.json 的完整 Schema。仓库原生规范不必在本章逐字段重复粘贴，但应保留其结构意图：

• manifest.json 应描述 Bundle 版本、profile、入口、sidecar 路径与完整性元数据
• devicespec.json 应描述平台类型、拓扑、通道、原生操作、时序与约束
• calset.json 应描述版本化校准上下文、单目标参数、成对参数以及资源引用

稳定性规则

Schema 稳定性非常重要，因为 Bundle、验证器、示例与 backend 集成都依赖一致的工件结构。说明性文本可以演进，但规范性结构变更必须是有意的、可版本化的。

与 Canonical Model 的关系

Schema 不替代语义。canonical UQCI model 定义含义，Schema 定义 interchange 与 validation 所需的机器可读结构。

换言之，Schema 文件应被视为结构契约，而不是语义解释的唯一来源。语义仍锚定在 canonical UQCI 模型与本规范各章之中。

与 OpenQASM 的关系

OpenQASM 导出可以引用基于 Schema 的 sidecar，但不能替代它们。设备与校准语义应保留在对应 sidecar Schema 中，而不是被过度编码进单一 QASM 文件。

编辑与仓库规则

本章应作为 Schema 纪律的总章存在。完整的机器可读定义应保留在仓库 Schema 文件中，而后续分章则聚焦说明各工件的角色，而不是重复冗长 JSON 清单。