开发指南类型系统
类型系统
Type14 数据声明统一采用 JSON Schema 2020-12，接口、精确引用与版本治理使用平台契约。
本章是百积木公共类型系统的统一规范入口。当前公共类型库为 baijimu-types 14.0.0，共享 Type Definition 文档协议为 schemaVersion: "5.0.0"。资源自己的 semanticVersion 与这两个版本相互独立。
数据声明统一采用 JSON Schema 2020-12。新版作者输入不再接受旧 DataType、Map 或数据 RefType；接口、方法、事件与服务绑定仍由平台模型描述。Type13 退役与历史资源迁移见兼容性与迁移，不能仅因公共库已发布就认为所有服务已完成切换。
按问题查规范
| 问题 | 权威章节 |
|---|---|
| 任意 JSON、对象开放性、数组、字典、组合与约束 | 数据类型 |
| 必填、null 和默认值 | 必填、可空与默认值 |
| Interface 的方法、事件和接口容器 | 接口与方法 |
| 共享文档、数据引用、接口引用和 Module 导入 | 命名类型与精确引用 |
| 兼容方向、历史消费者和迁移 | 兼容性与迁移 |
数据、接口与资源
| 层次 | 示例 | 作用 |
|---|---|---|
| 标准数据 Schema | {"type":"string"} 或 true | 描述允许的 JSON 值 |
| 混合 Type 位置的数据声明 | {"@type":"JsonSchema","schema":{"type":"string"}} | 在同一 Type 容器中区分数据和接口 |
| 可调用契约 | Interface、MethodDefinition | 描述方法、事件和调用签名 |
| 引用值 | ServiceReference | 绑定实现接口的服务，不是类型声明 |
| 共享类型资源 | Type Definition 的精确版本 | 管理身份、命名、发布与授权 |
公共 Type 变体为 JsonSchema、Interface、InterfaceMap、InterfaceList、MethodDefinition、RefType。其中 RefType 仅用于接口引用；数据引用在 schema 内使用标准 $ref。
参数、返回值等接受完整 Type 的位置使用 JsonSchema 包装；包装内的 schema、properties、items、$defs 和组合分支都是标准 Schema，不再逐层加平台 @type。共享文档的 dataSchema 直接承载一个标准 Schema 资源。
与其他规范的关系
- CModel 数据契约规定响应 envelope、错误及数据边界。
- 时间类型规定时间点、日期、时长的单位与边界转换。
- Type Definition 开发说明创建、发布和导入资源。
- 模块定义开发、Workflow、Agent 开发说明声明位置与各自采用的协议。
本地 Connector 的 payload_schema 等明确接收 JSON Schema 的字段直接填写 Schema，不加混合 Type 包装。某个消费者可以限制可接受的 Schema 能力，但必须明确拒绝不支持的声明，不能静默改写其含义。