命名类型与精确引用
Type Definition 5.0.0 的 dataSchema、interfaces、标准数据引用与平台接口引用。
Type Definition 提供稳定身份、命名与精确版本。数据正文是独立的 JSON Schema 资源，接口仍使用平台契约。创建与发布见 Type Definition 开发。
当前共享文档
{
"schemaVersion": "5.0.0",
"kind": "INTERFACE",
"rootType": "ProductProvider",
"dataSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "baijimu-type://example/123e4567-e89b-12d3-a456-426614174000@1.2.3",
"$defs": {
"Product": {
"type": "object",
"properties": { "sku": { "type": "string" } },
"required": ["sku"],
"additionalProperties": false
}
}
},
"interfaces": {
"ProductProvider": {
"methods": [
{
"name": "list",
"async": false,
"param_definitions": [],
"return_type": {
"@type": "JsonSchema",
"schema": {
"type": "array",
"items": {
"$ref": "baijimu-type://example/123e4567-e89b-12d3-a456-426614174000@1.2.3#/$defs/Product"
}
}
}
}
],
"events": []
}
}
}schemaVersion为5.0.0，不等于业务资源版本。dataSchema必须是对象形式的标准 Schema 资源；公共数据成员放在$defs中。注册的根$id必须匹配该定义的精确资源身份。interfaces是接口名到 Interface 正文的映射；其中的正文不带@type。独立 Type 位置的 Interface 才带标签。kind: "INTERFACE"的rootType选择interfaces中的成员；DATA_TYPE选择dataSchema.$defs中的成员；ENUM选择其中声明了非空enum的成员。DATA_TYPE仍是资源分类枚举，不表示旧@type: "DataType"格式仍可用。- 数据成员与接口成员不得重名。
dataSchema和interfaces都必须声明；无数据成员可用{}，无接口可用{}。 - 不再使用统一的
types命名表。methods/events是数组，$defs/interfaces/properties是映射。
示例的环境、UUID、版本和成员只说明语法。真实身份由类型目录与资源发布结果确定，不能直接复制示例 $id 发布自己的资源。
数据引用与接口引用
| 用途 | 引用 | 解析范围 |
|---|---|---|
| 同一 Schema 内数据定义 | {"$ref":"#/$defs/Product"} | 当前 Schema 资源的 $defs |
| 跨资源数据定义 | {"$ref":"baijimu-type://example/123e4567-e89b-12d3-a456-426614174000@1.2.3#/$defs/Product"} | 精确版本的数据 Schema |
| 已声明 anchor | {"$ref":"#Product"} | 当前 Schema 中的 $anchor: "Product"，不是平台成员名 |
| 同一文档的接口 | {"@type":"RefType","ref":"#ProductProvider"} | 当前文档的 interfaces |
| 跨文档接口 | {"@type":"RefType","ref":"baijimu-type://example/123e4567-e89b-12d3-a456-426614174000@1.2.3#ProductProvider"} | 精确版本的接口成员 |
接口里的每个内联 schema 有独立根作用域，局部 #/$defs/Product 不会自动指向外层文档的 dataSchema。上例因此使用完整数据 URI。$ref 指向数据 Schema，不能指向整个文档 envelope。
environmentKey + typeDefinitionId 标识定义，精确 semanticVersion 锁定不可变资源，fragment 标识数据路径、anchor 或接口成员。不能用 latest、版本范围、工作区 ID 或可变名称替代。
引用 URI 不授予权限，不会自动联网下载。调用方必须经身份与权限核验提供完整资源集合；库自身不持有网络、缓存或存储。数据递归遵循 JSON Schema 引用图，不能沿用旧类型的“所有循环都必须展开”规则；无实例进展的引用环仍拒绝。接口引用由平台按接口解析规则检查。
Module 导入声明
{
"typeImports": {
"contracts": {
"locator": {
"environmentKey": "example",
"typeDefinitionId": "123e4567-e89b-12d3-a456-426614174000"
},
"semanticVersion": "1.2.3"
}
}
}数据位置使用 $ref：
{
"@type": "JsonSchema",
"schema": { "$ref": "baijimu-type-import://contracts#/$defs/Product" }
}接口位置使用 RefType：
{ "@type": "RefType", "ref": "baijimu-type-import://contracts#ProductProvider" }别名只在当前 Module 作者作用域生效，必须存在于 typeImports。发布器展开为精确资源 URI，并保留数据引用的 JSON Pointer / anchor，不把数据引用改成平台接口引用。已发布共享文档不能依赖某个 Module 的别名。
发布新 Type Definition 不会自动替换旧 Module 的精确引用；Bundle 和 Runtime 不负责猜测类型版本。类型可读也不等于有权调用接口实现。