@guandata/guanonto-schemas

guanonto（观远本体平台）后端 API 的对外契约：

• 所有公开端点的 input/output Zod schema
• 共享 type / 枚举常量（ObjectPropertyType、RiskSeverity、ConnectorType...）
• HTTP 路径常量（API_PATHS.ontologies.list 等），避免对接方手写字符串

仅给 TS 对接方使用（decidex BFF、未来其他 TS 服务）。不带 fetch client，调用方自己拼 fetch 即可。

安装

# 在对接项目根目录创建 .npmrc（内容见公司内部 wiki）
echo '@guandata:registry=https://app.mayidata.com/nexus/repository/guandata-web/' >> .npmrc

pnpm add @guandata/guanonto-schemas

peer dependency：zod >= 4.0.0

本版本声明 CONSUMER_CONTRACT_GENERATION = "v1"；普通 schemas minor 发版不改变 HTTP contract generation。

用法

1. 调 list 接口

import { API_PATHS } from "@guandata/guanonto-schemas";

const res = await fetch(`${GUANONTO_BASE}${API_PATHS.ontologies.list}`, {
  headers: { authorization: `Bearer ${pat}` },
});
const data = await res.json();

2. 调 create 接口，input 用 schema 校验

import { createOntologySchema, API_PATHS } from "@guandata/guanonto-schemas";

const body = createOntologySchema.parse({
  name: "客户主题域",
  description: "支撑销售域分析",
  tags: ["sales"],
});

const res = await fetch(`${GUANONTO_BASE}${API_PATHS.ontologies.list}`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${pat}`,
    "content-type": "application/json",
  },
  body: JSON.stringify(body),
});

3. ConceptGroup expand（Agent 推理链路核心）

expand 一次返回 ConceptGroup + 它声明的所有 member（ObjectType / RelationType / RiskType / ActionType）detail，且 ObjectType 的 properties 和 instanceSources（0.6.0 起）直接内联。Agent 不用按 stableId 多次 round trip 就能拿到完整图，并能按对象直接定位数据集（instanceSources[].remoteResourceId = dsId）。

import {
  API_PATHS,
  type ExpandedConceptGroup,
  type ExpandedConceptGroupRiskView,
} from "@guandata/guanonto-schemas";

// 拉 draft（默认）
const draftUrl = `${GUANONTO_BASE}${API_PATHS.ontologies.conceptGroupExpand(
  ontologyId,
  conceptGroupStableId, // stableId 或 cuid 都可
)}`;
const draftRes = await fetch(draftUrl, {
  headers: { authorization: `Bearer ${pat}` },
});
const draft: ExpandedConceptGroup = await draftRes.json();
// draft.versionNo === null
// draft.objectTypes[i].properties 已内联
// draft.objectTypes[i].instanceSources 已内联（0.6.0 起；无绑定时为 []）
//   每条含 stableId / name / resourceKind(dataset|metric_topic) / remoteResourceId(=dsId/topicId) /
//   remoteResourceName / remoteResourcePath / primaryKeys / displayKey
//   （不含 connectorId / fieldsSnapshot / metricsSnapshot；
//    属性取值绑定改由 property.source 内联表达，0.7.0 起移除来源上的 fieldMappings）
// draft.relationTypes[i].sourceObjectTypeStableId / targetObjectTypeStableId 直接可用

// 拉指定历史版本（CLI 端如果绑定到 Version N，可以锁版本）
const v1Url = `${GUANONTO_BASE}${API_PATHS.ontologies.conceptGroupExpand(
  ontologyId,
  conceptGroupStableId,
  1,
)}`;
// version 模式下：detail.id 退化为 stableId（历史快照里 cuid 不存在）
// 找不到的 member 进入 unresolvedMembers，reason: "not_found"

// 拉轻量风险视图（draft only）：场景相关风险 + 关联对象 + 指标 + 缓解行动
const riskViewUrl = `${GUANONTO_BASE}${API_PATHS.ontologies.conceptGroupExpand(
  ontologyId,
  conceptGroupStableId,
  { view: "risk" },
)}`;
const riskView: ExpandedConceptGroupRiskView = await (
  await fetch(riskViewUrl, {
    headers: { authorization: `Bearer ${pat}` },
  })
).json();
// riskView.risks[i].source = "explicit" | "related"
// riskView.risks[i].riskType.description 是简短风险描述
// riskView.risks[i].riskType.detail 是更完整的风险说明
// riskView 不返回 objectTypes / relationTypes / instanceSources

错误 code：

• 404 version_not_found —— 传的 ?version=<n> 不存在
• 404 concept_group_not_found_in_version —— 版本里没有这个 ConceptGroup
• 400 invalid_version_param —— ?version= 非正整数

4. Risk Investigation Package（ADR 0021 风险优先探索）

risk-types get / API_PATHS.ontologies.riskTypeDetail 仍返回普通 RiskTypeDetail。当 Agent 已经从 ConceptGroup expand 找到具体风险后，再调用 riskTypeExpand 拉风险调查包：风险摘要 + 关联对象 + 引用指标 + 缓解行动摘要。该包是渐进探索入口，不展开对象完整属性、Instance Source、行动参数或执行契约。 风险摘要里的说明字段保持在 riskType 上：riskType.description 是简短描述，riskType.detail 是更完整说明。

import {
  API_PATHS,
  type RiskInvestigationPackage,
} from "@guandata/guanonto-schemas";

const res = await fetch(
  `${GUANONTO_BASE}${API_PATHS.ontologies.riskTypeExpand(
    ontologyId,
    riskStableIdOrId,
  )}`,
  { headers: { authorization: `Bearer ${pat}` } },
);
const pkg: RiskInvestigationPackage = await res.json();

// pkg.sourceEnvRef 是本体级环境绑定；不在 metric/action 上重复。
// pkg.referencedMetrics[i].metricId 有值时，caller 可直接走指标查询路径。

5. 运行时实例查询

import { lookupByIdsInputSchema, API_PATHS } from "@guandata/guanonto-schemas";

const params = lookupByIdsInputSchema.parse({ ids: ["1", "2", "3"] });

const url = new URL(
  API_PATHS.ontologies.instances(ontologyId, objectTypeId),
  GUANONTO_BASE,
);
url.searchParams.set("ids", params.ids.join(","));

const res = await fetch(url, { headers: { authorization: `Bearer ${pat}` } });

6. 拿响应类型（仅类型，不带 runtime parse）

import type { OntologyListItem, RuntimeInstance } from "@guandata/guanonto-schemas";

const json = (await res.json()) as { items: OntologyListItem[] };

旧端点尚未全部导出 response schema；新公共契约必须直接复用本包的 response schema，调用方不得另写平行 Wire Contract。Object Data Source Mutation 已按此规则导出完整请求、成功响应与 problem schema。

6.1 Object Data Source Mutation（0.15.0）

import {
  API_PATHS,
  objectDataSourceMutationProblemSchema,
  objectDataSourceMutationRequestSchema,
  objectDataSourceStateSchema,
} from "@guandata/guanonto-schemas";

const current = objectDataSourceStateSchema.parse(
  await (await fetch(`${GUANONTO_BASE}${API_PATHS.ontologies.objectTypeDataSource(oid, otId)}`)).json(),
);
const request = objectDataSourceMutationRequestSchema.parse({
  revision: current.revision,
  source: selectedDataset,
  bindings: [{ propertyId, fieldName: "customer_id" }],
});
const response = await fetch(
  `${GUANONTO_BASE}${API_PATHS.ontologies.objectTypeDataSource(oid, otId)}`,
  { method: "PUT", body: JSON.stringify(request) },
);
const result = response.ok
  ? objectDataSourceStateSchema.parse(await response.json())
  : objectDataSourceMutationProblemSchema.parse(await response.json());

7. OntologyDetail 自带 instanceSources 聚合（0.2.1 起，ADR 0007）

import type { OntologyDetail, InstanceSourceSummary } from "@guandata/guanonto-schemas";
import { API_PATHS } from "@guandata/guanonto-schemas";

const res = await fetch(`${GUANONTO_BASE}${API_PATHS.ontologies.detail(ontologyId)}`, {
  headers: { authorization: `Bearer ${pat}` },
});
const detail = (await res.json()) as OntologyDetail;

// 一次拉齐：所有 ObjectType + 它们绑定的 InstanceSource
const byObjectType = new Map<string, InstanceSourceSummary[]>();
for (const src of detail.instanceSources) {
  const list = byObjectType.get(src.objectTypeId) ?? [];
  list.push(src);
  byObjectType.set(src.objectTypeId, list);
}
// detail.objectTypes 列表渲染时，从 byObjectType.get(ot.id) 直接拿绑定，避免 N+1 sub-resource 调用

导出清单

设计时 schema (M2)：

• createOntologySchema / updateOntologySchema
• duplicateOntologySchema（0.6.0 起。另存为：POST API_PATHS.ontologies.duplicate(id)，把当前草稿含 connector 绑定复制为新本体，版本历史不复制）
• createObjectTypeSchema / updateObjectTypeSchema（0.4.0 起含可选单值领域标签 tag，传 null/空串清除）
• createRiskTypeSchema / createActionTypeSchema 等同样含 tag（0.5.0 起，语义与 ObjectType 一致）
• renameDomainTagSchema / RenameDomainTagResult（0.5.0 起，POST API_PATHS.ontologies.tagsRename(id) 批量重命名本体内领域标签）
• createObjectPropertySchema / updateObjectPropertySchema
• createRelationTypeSchema / updateRelationTypeSchema
• createRiskTypeSchema / updateRiskTypeSchema
• createActionTypeSchema / updateActionTypeSchema
• createConceptGroupSchema / updateConceptGroupSchema

版本化 + 导入导出 (M3 + M6 / ADR 0011，0.4.0 起为正式契约)：

• createOntologyVersionSchema
• ONTOLOGY_VERSION_SCHEMA_VERSION（0.8.0 起为 4）
• OntologyVersionDefinition 系列 type（v2 含 OntologyVersionDefinitionInstanceSource；objectType/riskType/actionType 含 tag: string | null，旧定义缺失按 null 处理）
• BIZONTOLOGY_EXPORT_FORMAT / BizOntologyExportManifest / BizOntologyExportFile
• importFileSchema / importSourceMappingSchema / importCreateRequestSchema / importReplaceRequestSchema（0.13.0 起 replace 可通过请求级 name? 原子改名；省略时保留目标名称）
• ImportPlanReport / ImportPlanItem / ImportConflict / ImportSkippedSource
• 0.3.x 的 importOntologySchema / ImportOntologyResult（裸 definition 导入）已移除

Connector + Environment + InstanceSource (M4)：

• CONNECTOR_TYPES / ConnectorType
• createConnectorSchema / updateConnectorSchema
• createGuandataEnvSchema / updateGuandataEnvSchema / rotateGuandataEnvSchema
• guandataEnvSlugSchema
• createInstanceSourceSchema / updateInstanceSourceSchema

运行时查询 (M5)：

• lookupByIdsInputSchema / searchInputSchema
• RuntimeInstance / RuntimeInstanceResult (type)

枚举 + Response type：

• OBJECT_PROPERTY_TYPES / OBJECT_PROPERTY_VALUE_SCOPES（0.7.0 起）/ RISK_SEVERITIES / ACTION_PARAMETER_TYPES / CONCEPT_GROUP_MEMBER_KINDS
• OntologySummary / OntologyListItem / OntologyDetail
• ObjectTypeSummary / ObjectPropertySummary / RelationTypeSummary / RiskTypeSummary / ActionTypeSummary / ConceptGroupSummary
• RiskInvestigationPackage / RiskInvestigationObject / RiskInvestigationMetric / RiskInvestigationAction（0.12.0 起：riskTypeExpand 返回的风险调查包）
• ExpandedConceptGroupRiskView / ConceptGroupRiskInvestigation / ConceptGroupRiskSource（0.12.1 起：conceptGroupExpand(..., { view: "risk" }) 返回的场景风险视图）
• ObjectTypeWithSources / ObjectTypeInstanceSourceRef（0.6.0 起：expand 与 object-type detail 内联的 source 裁剪视图）
• ConnectorSummary / GuandataEnvironmentSummary / InstanceSourceSummary

命名 alias（0.1.0 起，方便 list / detail 语义对齐）：

• ObjectTypeListItem（deprecated，改用 ObjectTypeSummary；1.0.0 移除）
• ObjectTypeDetail（deprecated，改用 ObjectTypeWithSources；1.0.0 移除，detail 比 list 多内联 instanceSources）
• ObjectPropertyListItem / ObjectPropertyDetail
• RelationTypeListItem / RelationTypeDetail
• RiskTypeListItem / RiskTypeDetail
• ActionTypeListItem / ActionTypeDetail
• ConceptGroupListItem / ConceptGroupDetail
• InstanceSourceListItem / InstanceSourceDetail

路径常量：

• API_PATHS.health
• API_PATHS.me
• API_PATHS.platform.*（auth / callers / service-keys / guandata-environments / audit-log）
• API_PATHS.admin.*（tokens / namespaces）
• API_PATHS.connectors.*
• API_PATHS.ontologies.*（含 versions / versionExport / object-types / properties / instances / instance-sources / relation-types / risk-types / action-types / concept-groups / import / importReplace / duplicate / tagsRename）
• API_PATHS.ontologies.objectTypeDataSource(ontologyId, objectTypeId)（GET 当前状态；PUT 原子提交完整目标状态）

路径兼容 alias（0.1.0 起；以下 9 个已 deprecated，1.0.0 移除）：

• objectType → 改用 objectTypeDetail
• objectTypeProperties → 改用 properties；objectTypeProperty → 改用 propertyDetail
• objectTypeInstanceSources → 改用 instanceSources；objectTypeInstanceSource → 改用 instanceSourceDetail
• relationType / riskType / actionType / conceptGroup → 改用各自 *Detail

其它等价入口：

• riskTypeShow / riskTypeExpand ≡ /risk-types/:id/expand（0.12.0 起，返回 RiskInvestigationPackage）
• conceptGroupExpand(ontologyId, conceptGroupId, { view: "risk" }) ≡ /concept-groups/:id/expand?view=risk（0.12.1 起，返回 ExpandedConceptGroupRiskView）

乐观锁（0.1.0 起）

所有 update*Schema 现在都接受可选的 expectedUpdatedAt（ISO-8601）：

import { updateObjectTypeSchema, API_PATHS } from "@guandata/guanonto-schemas";

const body = updateObjectTypeSchema.parse({
  name: "新名字",
  expectedUpdatedAt: previousFetched.updatedAt, // 防 last-write-wins
});

const res = await fetch(`${GUANONTO_BASE}${API_PATHS.ontologies.objectTypeDetail(oid, otId)}`, {
  method: "PATCH",
  body: JSON.stringify(body),
});

if (res.status === 409) {
  const problem = await res.json();
  if (problem.code === "concurrent_update") {
    // problem.currentUpdatedAt 是服务端当前 updatedAt，UI 据此提示用户刷新
  }
}

• 不传 expectedUpdatedAt：兼容单写场景，不启用乐观锁
• 冲突时：409 { code: "concurrent_update", currentUpdatedAt }

错误响应 problem+json（0.1.0 起）

所有 4xx / 5xx 错误响应是 RFC 7807 application/problem+json：

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "...",
  "code": "duplicate_name"
}

code 字段集合（caller UI 可据此区分）：

| status | code | |---|---| | 403 | ontology_not_allowed | | 409 | duplicate_name | | 409 | concurrent_update（额外字段 currentUpdatedAt） | | 409 | referenced_by_relation_type / referenced_by_concept_group | | 422 | invalid_dataset_field |

非空 allowedOntologyIds 的 PAT 访问白名单外既有本体，或调用 create、 import-create、duplicate 创建新本体时，返回 403 ontology_not_allowed。空白名单 PAT 与 svc-key 不受此边界影响（ADR 0009）。

版本规则

• 新增字段（非 breaking） → minor（0.x.0）
• 字段重命名 / 删除 → major + 更新对接方

Changelog

• Unreleased
  • 补齐 ADR 0010 的 deprecation 提示：ObjectTypeListItem / ObjectTypeDetail 与 9 个路径兼容 alias 将在 1.0.0 移除；运行时路径和值不变
• 0.15.0（2026-07-22）· Object Data Source Mutation（ADR 0023）
  • 新增 objectDataSourceMutationRequestSchema、objectDataSourceStateSchema、objectDataSourceMutationProblemSchema 及推导类型
  • 新增 API_PATHS.ontologies.objectTypeDataSource(...)；使用对象级 revision、完整目标状态和单事务写入
  • 数据集命令只管理 Instance Source、instance 属性和字段绑定，不接受或修改 object_metric
• 0.14.0（2026-07-20）· Ontology 归属者显示名
  • OntologySummary（及 OntologyListItem / OntologyDetail）新增 ownerDisplay: string | null，来源为 Actor.display；owner 缺失或从未上报显示名时为 null
  • caller 通过新请求头 X-Actor-Display-Enc（encodeURIComponent 编码的 UTF-8）随 X-Actor-Ref 上报显示名；旧头 X-Actor-Display（原样入库）仅在新头缺失时兜底
• 0.13.0（2026-07-17）· ADR 0022 replace-import 可选原子改名
  • importReplaceRequestSchema 新增可选 name；显式传入时与 definition replace 在同一事务内更新，省略时保持既有名称
  • 同 namespace 重名在 dry-run 中返回 duplicate_name conflict，apply 返回 409 duplicate_name 并整体回滚
• 0.12.1（2026-06-24）· ConceptGroup risk view
  • API_PATHS.ontologies.conceptGroupExpand(ontologyId, conceptGroupId, { view: "risk" }) 支持拼接 ?view=risk
  • 新增 ExpandedConceptGroupRiskView / ConceptGroupRiskInvestigation / ConceptGroupRiskSource
  • view=risk 返回场景显式风险与关联风险的轻量调查视图，不返回完整对象属性、关系、Instance Source 或行动参数
• 0.12.0（2026-06-24）· ADR 0021 风险调查包契约
  • 新增 RiskInvestigationPackage 及其子类型：RiskInvestigationObject / RiskInvestigationMetric / RiskInvestigationAction
  • 新增 API_PATHS.ontologies.riskTypeExpand(ontologyId, riskTypeIdOrStable) 与 alias riskTypeShow(...)，路径为 /api/v1/ontologies/:ontologyId/risk-types/:riskTypeId/expand
  • RiskTypeDetail / API_PATHS.ontologies.riskTypeDetail 语义保持不变，仍是普通风险摘要；调查包必须显式走 /expand
• 0.8.3（2026-06-16）· expand / object-types show 指标 subType 富化 + transitive 关联桶（ADR 0016）
  • 属性级指标 subType：ObjectPropertySummary 新增可选 metric: { subType } | null（新增 ObjectPropertyMetricRef）。object_metric 属性在 expand 与 object-types show 富化时回填指标子类型（ATOMIC | COMPOSITE | DERIVED），未命中快照为 null；其余端点不带 metric。只投影 subType，不投影 status
  • transitive 风险/行动：ExpandedConceptGroup 新增 relatedRiskTypes / relatedActionTypes——绑定到场景成员对象但非显式成员的风险，及缓解（成员风险 ∪ related 风险）但非显式成员的行动。riskTypes / actionTypes 仍严格 = 显式成员，语义不变
  • 纯增量、向后兼容：新增字段均可选；本体 schemaVersion 维持 v4
• 0.8.2（2026-06-15）· RiskType 写入契约支持 mitigatedByActionIds
  • 风险侧维护风险↔行动 N:N：createRiskTypeSchema / updateRiskTypeSchema 新增 mitigatedByActionIds: string[]（行动 ID 列表，可选、默认 []、去重），与行动侧 mitigatedRiskIds 互为反向、同一份关系；写入语义为全量覆盖该风险的关联行动并同步反向。非法行动 ID（不属于同一本体）报 400。RiskTypeSummary.mitigatedByActionIds 读写一致
• 0.8.1（2026-06-15）· MetricSnapshotEntry 新增 subType / status（透传）
  • 指标快照富字段：MetricSnapshotEntry 新增可选 subType（ATOMIC | COMPOSITE | DERIVED，新增 METRIC_SUB_TYPES / MetricSubType）与 status: string（如 ONLINE），随 metricsSnapshot 在 createInstanceSourceSchema / updateInstanceSourceSchema 写入、InstanceSourceSummary 读出，并进入版本快照与导入（import metric 条目同步放开）；guanonto 不解释取值，仅透传供风险编辑器展示。两字段均 optional/nullish，老 { metricId, name } 调用与历史快照不变；本体 schemaVersion 维持 v4
• 0.8.0（2026-06-15）· 风险绑定关系 + dataset 源指标绑定放开（ADR 0014）
  • dataset 源放开指标：dataset 类型 Instance Source 可同时携带 fieldsSnapshot 与 metricsSnapshot（不再互斥）；Property Source 的 metricId 绑定不再要求 metric_topic 源——dataset / metric_topic 均可，仍校验 metricId ∈ metricsSnapshot 且属性 valueScope=object_metric（否则 invalid_source_metric / property_source_scope_mismatch）
  • RiskType 新增对象绑定：objectTypeStableIds: string[]（风险 ↔ 对象 N:N），进入 createRiskTypeSchema / updateRiskTypeSchema / RiskTypeSummary / 版本快照；非本体内对象返回 invalid_object_reference
  • RiskType 新增引用指标：referencedMetricStableIds: string[]（引用 object_metric 属性 stableId）；非本体内 object_metric 属性返回 invalid_metric_reference。富文本 @ token 由 caller 维护，权威引用列表以此为准
  • 版本 definition 升 v4：ONTOLOGY_VERSION_SCHEMA_VERSION 升为 4，正式导出/导入仅接受 v4（旧 v1/v2/v3 快照拒绝）；OntologyVersionDefinitionRiskType 新增 objectTypeStableIds + referencedMetricStableIds
  • 旧数据兼容：两数组字段默认空数组；存量风险与无指标 dataset 源行为不变
• 0.7.0（2026-06-13）⚠️ breaking · Biz Ontology 数据来源模型演进（ADR 0012）
  • Object Property 取值粒度：新增 valueScope（instance | object_metric，默认 instance），新增枚举 OBJECT_PROPERTY_VALUE_SCOPES / ObjectPropertyValueScope；createObjectPropertySchema / updateObjectPropertySchema 可写，ObjectPropertySummary 内联返回
  • Instance Source 改为对象级远端资产来源：resourceKind 收敛为枚举 dataset | metric_topic（新增 INSTANCE_SOURCE_RESOURCE_KINDS / InstanceSourceResourceKind）；metric_topic 新增指标快照 metricsSnapshot: { metricId, name }[]（新增 MetricSnapshotEntry），与 dataset 的 fieldsSnapshot 对称；primaryKeys / displayKey 仅 dataset 适用
  • 移除 Instance Source 系列（createInstanceSourceSchema / updateInstanceSourceSchema / InstanceSourceSummary / ObjectTypeInstanceSourceRef）及 expand/detail 内联 instanceSources 上的 fieldMappings
  • Property Source 提升为一等绑定：新增 putPropertySourceSchema + API_PATHS.ontologies.propertySource(id, otId, pId)（PUT 绑定 / DELETE 解绑，一属性最多 1 个来源）；新增 PropertySourceSummary / PropertySourceRef；ObjectPropertySummary 内联 source: PropertySourceRef | null（避免 N+1）。取值标识二选一：dataset → fieldName（∈ fieldsSnapshot，否则 invalid_source_field）；metric_topic → metricId（∈ metricsSnapshot，否则 invalid_source_metric）；valueScope 与绑定不一致报 property_source_scope_mismatch
  • 版本 definition 升 v3：ONTOLOGY_VERSION_SCHEMA_VERSION 升为 3，正式导出/导入仅接受 v3（旧 v1/v2 快照拒绝）；OntologyVersionDefinitionObjectProperty 新增 valueScope + source，OntologyVersionDefinitionInstanceSource 新增 metricsSnapshot
• 0.6.0（2026-06-12）
  • expand / object-type detail 内联 instanceSources：新增 ObjectTypeInstanceSourceRef / ObjectTypeWithSources，ExpandedConceptGroup.objectTypes 与 ObjectTypeDetail 升级为带 sources 的形状（Agent 按对象定位数据集，不再按名称猜）
  • 旧版本快照（v1）无 instanceSources 时返回空数组；object-types list 与 OntologyDetail 顶层聚合不变
  • 新增 duplicateOntologySchema + API_PATHS.ontologies.duplicate(id)（本体另存为）
• 0.5.0（2026-06-11）
  • RiskType / ActionType 新增可选单值领域标签 tag（语义同 ObjectType）
  • 新增 renameDomainTagSchema / RenameDomainTagResult + API_PATHS.ontologies.tagsRename(id)（批量重命名领域标签）
• 0.4.0（2026-06-11）
  • 正式导入导出契约（ADR 0011 / M6）：importFileSchema 等 import 系列、BizOntologyExportFile 系列；ONTOLOGY_VERSION_SCHEMA_VERSION 升为 2（definition 含 instanceSources）
  • ObjectType 新增可选单值领域标签 tag；移除 0.3.x 裸 definition 导入契约
• 0.3.0（2026-06-08）
  • PAT 新增 allowedOntologyIds：把 PAT 权限粒度从「namespace 内全部」收缩到「白名单内 ontology」（ADR 0009）
  • issueAdminTokenInputSchema 新导出：签发 PAT 时支持 allowedOntologyIds?: string[]（最多 100 个）
  • IssuedAdminToken / AdminTokenSummary 类型导出，含 allowedOntologyIds: string[]
  • 新增 GUANONTO_ERROR_CODES.ONTOLOGY_NOT_ALLOWED（HTTP 403）：PAT 命中白名单边界
  • 兼容老 PAT：allowedOntologyIds = [] 等价于「namespace 内全部」（与历史行为一致）
  • svc-key 路径不受影响（caller BFF 仍持有全权）
• 0.2.2（2026-06-08）
  • instanceSourceUpsertSchema.connectorId 放宽：max 60 → max 120（ADR 0008）
  • guanonto 不再做 connectorId 存在性校验，视为 caller-side opaque 外部引用
  • 解决 Decidex 透传 UserConnector UUID（36 char）时被 guanonto 强校验拒绝的问题
  • 非 breaking：长度仅放宽、字段名 / 可选性不变；调用方仍可在自己侧维护语义
• 0.2.1（2026-06-08）
  • OntologyDetail 顶层新增 instanceSources: InstanceSourceSummary[] 字段（ADR 0007）
  • 解决 Decidex BizOntology Studio 首屏拿绑定 dataset 需要 N+1 sub-resource 调用的问题
  • 非 breaking：ObjectTypeSummary 与所有 sub-resource endpoint 保持不变
• 0.2.0（2026-06-08）
  • 新增 ConceptGroup expand 路径（API_PATHS.ontologies.conceptGroupExpand(ontologyId, cgId, versionNo?)）
  • 新增 expand 响应类型：ExpandedConceptGroup、ExpandedRelationType、UnresolvedConceptGroupMember
  • 新增错误 code：version_not_found、concept_group_not_found_in_version、invalid_version_param
• 0.1.1（2026-06-08）
  • 修复 dual package exports：补 CJS 输出（dist/index.cjs）与 require 条件，解决 tsx + node:test 等 CJS loader 的 ERR_PACKAGE_PATH_NOT_EXPORTED
• 0.1.0（2026-06-08）
  • 新增 expectedUpdatedAt 乐观锁字段（所有 update schema）
  • 新增 problem+json 的 code 字段集合
  • 新增 list / detail type alias
  • 新增 API_PATHS self-explained alias（objectType / objectTypeProperty 等）
  • 老命名（objectTypeDetail / properties 等）保留兼容
• 0.0.1-rc.1（2026-06-08）
  • 初版：M2–M6 全部 schema + API_PATHS

未来切换到 OpenAPI 自动生成时（ADR 0003 A 方案），这个包仍然保留（schema 是单一源，OpenAPI 由它派生）。

发包

cd packages/guanonto-schemas
# 1. 改 package.json version
# 2. 确保 .npmrc 含有效凭证（不要 commit）
pnpm build
npm publish