---
docStatus: current
---

# 类型系统

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 退役与历史资源迁移见[兼容性与迁移](/development/type-system/compatibility/)，不能仅因公共库已发布就认为所有服务已完成切换。

## 按问题查规范

| 问题                        | 权威章节                                                       |
| ------------------------- | ---------------------------------------------------------- |
| 任意 JSON、对象开放性、数组、字典、组合与约束 | [数据类型](/development/type-system/data-types/)               |
| 必填、null 和默认值              | [必填、可空与默认值](/development/type-system/data-types/#必填可空与默认值) |
| Interface 的方法、事件和接口容器     | [接口与方法](/development/type-system/interfaces/)              |
| 共享文档、数据引用、接口引用和 Module 导入 | [命名类型与精确引用](/development/type-system/references/)          |
| 兼容方向、历史消费者和迁移             | [兼容性与迁移](/development/type-system/compatibility/)          |

## 数据、接口与资源

| 层次              | 示例                                                  | 作用                  |
| --------------- | --------------------------------------------------- | ------------------- |
| 标准数据 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 数据契约](/development/data-contracts/)规定响应 envelope、错误及数据边界。
- [时间类型](/development/data-contracts/time/)规定时间点、日期、时长的单位与边界转换。
- [Type Definition 开发](/development/bundle-development/type-definition-development/)说明创建、发布和导入资源。
- [模块定义开发](/development/bundle-development/module-development/module-definition/)、[Workflow](/features/workflows/)、[Agent 开发](/development/bundle-development/agent-development/)说明声明位置与各自采用的协议。

本地 Connector 的 `payload_schema` 等明确接收 JSON Schema 的字段直接填写 Schema，不加混合 Type 包装。某个消费者可以限制可接受的 Schema 能力，但必须明确拒绝不支持的声明，不能静默改写其含义。