Thing Model v1 alpha 1 说明

本页帮助中文用户理解协议。带标签版本中的英文规范、JSON Schema、测试夹具和 TCK 才是规范性依据。

Thing Model 是不可变、行业中立的定义，用来描述配置属性、边缘观测点位与受治理能力。它不包含租户实例、实时值、凭据、寄存器绑定或客户拓扑。

最新发布版本是 v0.1.0-alpha.3。当前 0.1.0-alpha.4 内容是尚未发布的开发目标，仍处于实验阶段，不是生产模型目录。

修订身份与摘要

每个已发布修订都有一个 model_id、规范正整数 revision 和规范制品摘要。摘要属于外部发布记录，因为自摘要的 Thing Model 无法把自身摘要包含在摘要输入中，所以 thing-model.schema.json 有意不包含摘要字段。

禁止把同一修订号复用于不同的规范字节。属性、点位和能力三个命名空间之间的键必须唯一；这是 JSON Schema 之外的语义验证规则。每项能力内部的参数键也必须唯一，避免请求载荷产生歧义。

发布摘要由 sha256: 与 RFC 8785 JCS 规范化后的完整 Thing Model 对象的 SHA-256 小写结果组成。发布包装对象和租户元数据都不进入摘要投影。机器可读规则见 profiles/thing-model/v1alpha1/publication.json。

权威边界

属性属于不可变制品修订。变更必须通过制品部署或明确的边缘本地路径应用，不能直接写字段。
点位是边缘权威的只读观测。云端历史与投影都不是实时状态权威。
能力声明边缘端可能理解的操作。每项能力默认拒绝，必须声明权限、风险等级、确认策略、幂等性、到期时间和审计策略，并且只能作为受治理作业执行。边缘端对接纳、拒绝、到期或应用拥有最终决定权。

期望、报告与已应用是三种不同事实。期望表示云端意图；报告表示边缘对支持情况的观测；已应用表示边缘上报的部署证据。不能仅因消息已经发出或收到传输确认，就从一种事实推断出另一种。

状态为 applied 的观测必须携带非空模型引用和 applied_at_ms。not-applied 必须携带空模型引用，并且没有应用时间；applying 与 failed 标识尝试应用的模型，但不能伪造应用时间。根字段 observed_at_ms 为每种观测状态提供时间戳。

Voltage 迁移配置档

结构迁移规则如下：

P 迁移为 properties；
M 迁移为 points；
A 迁移为 capabilities；
pName 迁移到核心模型之外的分类或组合元数据；
旧数值标识保留为带命名空间的别名，不能作为全局标识。

单位拼写需要规范化，同时把旧拼写保留为来源证据。来源类型含糊、数组被表示为标量、含义重复或单位不确定时，必须生成明确迁移诊断，导入器不能静默猜测。

最小测试夹具在结构上参考 EvanL1/voltage-product-lib 的提交 7c4eec680f8b5e9a76a57c08078a41b9d5b4550c。导入时，该源仓库只有 README 中的 MIT 声明，没有独立 LICENSE，因此没有复制完整目录。该夹具不是具有规范效力的能源模型包。

与 W3C Web of Things 的关系

这套词汇与 W3C Web of Things 的属性、事件、动作和可复用 Thing Model 对齐，为未来导入与导出保留路径。JSON-LD 处理不是 v1 alpha 核心要求。WoT 动作只能映射为 Aether 能力声明，绝不能直接授予物理执行权限。

Thing Model alpha.4 开发目标不是生产能力授权，也不能绕过边缘策略。