Skip to content

Schema 中立原则 ​

面向映射配置者与开发者 — 约定 Olink Schema 层如何保持多品牌、多出口可用。配套:标准设备模型、标准枚举、设备映射参考。

Olink 做多平台桥接:各品牌适配器把设备送进统一模型,再按需出到 HomeKit、Matter 等。中间这一层就是 Schema。若 Schema 被某一厂商或某一出口绑死,后面每加一个平台都要返工。

一句话定义 ​

Schema 是多品牌、多出口共享的能力语义契约:用中立命名与规范枚举表达「设备能做什么」;厂商差异进 Input,生态差异与能力裁剪进 Output;信息损失只允许发生在出口边界,且必须可文档化。

text
品牌真实世界 ──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(见 标准枚举)。新增或合并档位前问:

  1. 是否至少有两个集成,或两个出口会用到这一语义?
  2. 若只有一侧需要细档:应在 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 变成了第一出口的影子

治理(让原则可执行) ​

  1. 单一真相
    规范枚举以 schemas/enums/*.toml 为准;属性侧优先 enum = "id",避免长期维护第二套互不同步的 value_list。

  2. 变更分级

    • Breaking: 改已有规范值的含义、删除 required、改 id
    • 兼容: 新增 optional 属性/服务、新增枚举档(旧档含义不变)
  3. 双出口冒烟(建议)
    每个核心枚举至少覆盖:1 个 Input 集成 ×(HAP 若适用 + Matter 若适用)的对照或 roundtrip,防止只为单侧改表。

  4. 文档即契约
    标准设备模型 / 标准枚举 由 schema 生成;改 TOML 后执行 npm run docs:gen-devices / docs:gen-enums。本页原则不替代生成页,只约束「怎么改 TOML」。

与三层映射的关系 ​

text
Input(品牌)     Schema(中立)        Output(生态)
方言、脏数据  →   能力 + 规范枚举   →   裁剪、折叠、合规
可多、可怪        少而稳               允许不完美

写映射时:

  • 问「这是品牌差异还是能力语义?」→ 前者 Input,后者 Schema
  • 问「这是生态展示限制还是家居本质?」→ 前者 Output,后者 Schema

相关链接 ​