---
docStatus: current
---

# 命名类型与精确引用

Type Definition 5.0.0 的 dataSchema、interfaces、标准数据引用与平台接口引用。

Type Definition 提供稳定身份、命名与精确版本。数据正文是独立的 JSON Schema 资源，接口仍使用平台契约。创建与发布见 [Type Definition 开发](/development/bundle-development/type-definition-development/)。

## 当前共享文档

```json
{
  "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 导入声明

```json
{
  "typeImports": {
    "contracts": {
      "locator": {
        "environmentKey": "example",
        "typeDefinitionId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "semanticVersion": "1.2.3"
    }
  }
}
```

数据位置使用 `$ref`：

```json
{
  "@type": "JsonSchema",
  "schema": { "$ref": "baijimu-type-import://contracts#/$defs/Product" }
}
```

接口位置使用 `RefType`：

```json
{ "@type": "RefType", "ref": "baijimu-type-import://contracts#ProductProvider" }
```

别名只在当前 Module 作者作用域生效，必须存在于 `typeImports`。发布器展开为精确资源 URI，并保留数据引用的 JSON Pointer / anchor，不把数据引用改成平台接口引用。已发布共享文档不能依赖某个 Module 的别名。

发布新 Type Definition 不会自动替换旧 Module 的精确引用；Bundle 和 Runtime 不负责猜测类型版本。类型可读也不等于有权调用接口实现。