Schema 中立原则
面向映射配置者与开发者 — 约定 Olink Schema 层如何保持多品牌、多出口可用。配套:标准设备模型、标准枚举、设备映射参考。
Olink 做多平台桥接:各品牌适配器把设备送进统一模型,再按需出到 HomeKit、Matter 等。中间这一层就是 Schema。若 Schema 被某一厂商或某一出口绑死,后面每加一个平台都要返工。
一句话定义
Schema 是多品牌、多出口共享的能力语义契约:用中立命名与规范枚举表达「设备能做什么」;厂商差异进 Input,生态差异与能力裁剪进 Output;信息损失只允许发生在出口边界,且必须可文档化。
品牌真实世界 ──Input──▶ 中立 Schema ──Output──▶ 各生态展示世界
↑ ↑ ↑
允许脏、多、怪 少、稳、可测 允许裁剪、折叠Schema 是什么 / 不是什么
| Schema 是 | Schema 不是 |
|---|---|
| 跨品牌、跨出口的能力语义(开关、目标温度、运行模式…) | MIoT / 海尔 / 追觅等字段的直接拷贝 |
| 稳定、可版本化的中间契约 | HAP Characteristic / Matter Attribute 的并集清单 |
| 「落盘后各集成与出口只认这一套值」 | 为某一 App UI 定制的展示模型 |
中立自检: 删掉所有 Input / Output 映射后,只看 Schema,一个不懂米家也不懂 HomeKit 的人仍能理解设备「能干什么」。过不了 → 已被某侧污染。
五条硬原则(MUST)
P1 — 语义优先,协议次之
命名用能力语言:target-temperature、ac-op-mode、power-state。
不要:miot-piid-xxx、TargetHeaterCoolerState、某品牌内部码当属性 id。
出口专有概念(HKSV 结构、Matter Endpoint 树、HAP 配件类别细节)留在 Output / 桥接运行时,不塞进 Schema 属性名。
P2 — 枚举是家居语义档,不是「最大公约数糊弄」
规范枚举定义在 schemas/enums/*.toml(见 标准枚举)。新增或合并档位前问:
- 是否至少有两个集成,或两个出口会用到这一语义?
- 若只有一侧需要细档:应在 Schema 保留细档、在另一侧 Output 折叠并写明损耗;还是在 Schema 里先合并?
优先保留语义、在出口折叠;避免在 Schema 里不可逆地丢掉信息。
映射使用方式:属性写 enum = "<id>"。若同属性已写显式 transform,则不读枚举表(与引擎行为一致)。
P3 — 必选 = 该类设备的最小可理解集
device.required / service.required 只放「没有就不成其为这类设备」的能力。
- 灯:至少
power-state - 某一出口「配件合规必须有」、但语义上非本质 → 用 optional,或只在该 Output 侧校验
不要把「HomeKit 说明书里写了必选」直接写成 Schema 全局 required。
P4 — 一台设备一种主类型;复合能力用 optional 服务
浴霸 = 加热类主类型 + optional light;不要为「带灯浴霸」再造 bath-heater-with-light 污染类型树。
新类型前先问:能否用「已有 device + optional service」表达?
P5 — 变换单向归属
| 方向 | 归属 |
|---|---|
| 厂商码 ↔ schema | 仅 schemas/enums 的 inputs.*,或 Input 层 transform |
| schema ↔ HAP / Matter / … | 仅 outputs.*,或 Output 适配器 |
禁止在 Input 里「顺手」写成 HAP/Matter 最终值;禁止在 Output 里回写厂商方言。
变更决策表
改 Schema 前填一行;答案偏「为单侧迁就」则改方案:
| 问题 | 中立时应接近 |
|---|---|
| 去掉 Input 后,该字段还有独立语义吗? | 有 → 可进 Schema |
| 是否只为迁就某一出口才加? | 是 → 优先 Output 或 optional |
| 枚举合并是否造成不可逆信息丢? | 会 → Schema 保留细档,出口再折叠 |
| 新类型能否用已有类型 + optional 服务? | 能 → 不新建 device |
| 单位/量纲冲突(如色温)? | Schema 定一种规范单位,出口再转 |
正反例
例 1:空调运行模式(ac-op-mode)
现状(简): 规范值多为送风 / 制热 / 制冷;部分品牌「除湿」在 Input 侧并入制冷等。
| 做法 | 评价 |
|---|---|
| Schema 只有三档,除湿在 Input 并进制冷 | 实现简单,但中枢已丢除湿语义;Matter 若支持 Dry 也找不回来 |
| Schema 增加「除湿」档;HAP Output 折叠到制冷或送风,并在枚举/文档注明 | 更中立:损失发生在出口边界,且可说明 |
多平台目标下,后一种更符合本原则。既有三档表若短期不改,至少在 标准枚举 与映射注释中标明「除湿等已在 Input 折叠」,避免后人以为 Schema 等价于全品牌能力全集。
例 2:扫地机状态(vacuum-status)
较好实践: 规范值(Idle / Running / Paused / …)与品牌无关;米家 / 追觅 / 石头在 inputs.*.vacuum 做厂商码映射,Matter 在 outputs.matter 映射。型号差异用 models."…" 整表覆盖,不把某品牌状态机写进规范值名。
注意:models 覆盖越多越难审计——新增覆盖时应对照默认表做 diff,并尽量补一条集成测试。
例 3:反例 — 属性 id 直接用 HAP 名
把 schema 属性叫成 TargetHeaterCoolerState,Input 从米家映射过去。
- 看起来「出 HomeKit 很快」
- Matter / 其它出口只能跟着 HAP 词汇走,或再做一次别名
- 违背 P1:Schema 变成了第一出口的影子
治理(让原则可执行)
单一真相
规范枚举以schemas/enums/*.toml为准;属性侧优先enum = "id",避免长期维护第二套互不同步的value_list。变更分级
- Breaking: 改已有规范值的含义、删除 required、改 id
- 兼容: 新增 optional 属性/服务、新增枚举档(旧档含义不变)
双出口冒烟(建议)
每个核心枚举至少覆盖:1 个 Input 集成 ×(HAP 若适用 + Matter 若适用)的对照或 roundtrip,防止只为单侧改表。文档即契约
标准设备模型 / 标准枚举 由 schema 生成;改 TOML 后执行npm run docs:gen-devices/docs:gen-enums。本页原则不替代生成页,只约束「怎么改 TOML」。
与三层映射的关系
Input(品牌) Schema(中立) Output(生态)
方言、脏数据 → 能力 + 规范枚举 → 裁剪、折叠、合规
可多、可怪 少而稳 允许不完美写映射时:
- 问「这是品牌差异还是能力语义?」→ 前者 Input,后者 Schema
- 问「这是生态展示限制还是家居本质?」→ 前者 Output,后者 Schema