Compare commits
8 Commits
03e20a7c87
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| 4756f19073 | |||
| d3b6425a66 | |||
| b615bfa9e2 | |||
| 6498395ed8 | |||
| f78d95d98d | |||
| e66d62ed6a | |||
| fa04055e57 | |||
| f552dc75f9 |
@ -15,7 +15,7 @@ WH Telemetry Protocol（简称 **WHTP**）是一套面向物联网场景的 **JS
|
||||
1. 阅读主规范 [schema.md](schema.md)，了解字段定义与类型系统。
|
||||
2. 查看 [example.jsonc](example.jsonc) 获取完整示例。
|
||||
3. 若采用 MQTT 作为载体，参考 [mqtt.md](mqtt.md) 的主题、QoS、Retain 与连接安全实践。
|
||||
4. 参见 [schema.json](schema.json) 获取 [JSON Schema](https://json-schema.org/) 定义。使用 [ATLASSIAN JSON Schema Viewer](https://json-schema.app/view/%23?url=https%3A%2F%2Fweihua-iot.cn%2Fschema.json) 在线可视化/校验。
|
||||
4. 参见 [schema.json](schema.json) 获取 [JSON Schema](https://json-schema.org/) 定义。使用 [ATLASSIAN JSON Schema Viewer](https://json-schema.app/view/%23?url=https%3A%2F%2Fgit.weihua-iot.cn%2Fcrosstyan%2Fwhtp%2Fraw%2Fbranch%2Fmain%2Fschema.json) 在线可视化/校验。
|
||||
|
||||
## 仓库结构
|
||||
|
||||
|
||||
93
schema.json
93
schema.json
@ -1,6 +1,6 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://example.com/wh-telemetry.schema.json",
|
||||
"$id": "https://git.weihua-iot.cn/crosstyan/whtp/raw/branch/main/schema.json",
|
||||
"title": "WH Telemetry Protocol v1 Message",
|
||||
"description": "JSON Schema definition for a WH Telemetry Protocol (WHTP) telemetry message.",
|
||||
"type": "object",
|
||||
@ -39,41 +39,7 @@
|
||||
"pattern": "^[A-Za-z0-9_-]{21}$"
|
||||
},
|
||||
"dev_type": {
|
||||
"description": "Device model identifier.",
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"oneOf": [
|
||||
{
|
||||
"required": [
|
||||
"type_id"
|
||||
],
|
||||
"properties": {
|
||||
"type_id": {
|
||||
"type": "string",
|
||||
"format": "nanoid",
|
||||
"pattern": "^[A-Za-z0-9_-]{21}$"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
{
|
||||
"required": [
|
||||
"type_name"
|
||||
],
|
||||
"properties": {
|
||||
"type_name": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
"$ref": "#/definitions/DeviceType"
|
||||
},
|
||||
"timestamp": {
|
||||
"$ref": "#/definitions/Timestamp"
|
||||
@ -220,6 +186,43 @@
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"DeviceType": {
|
||||
"description": "Device model identifier.",
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"oneOf": [
|
||||
{
|
||||
"required": [
|
||||
"type_id"
|
||||
],
|
||||
"properties": {
|
||||
"type_id": {
|
||||
"type": "string",
|
||||
"format": "nanoid",
|
||||
"pattern": "^[A-Za-z0-9_-]{21}$"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
{
|
||||
"required": [
|
||||
"type_name"
|
||||
],
|
||||
"properties": {
|
||||
"type_name": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"FieldMetadata": {
|
||||
"type": "object",
|
||||
"description": "Metadata describing a field value.",
|
||||
@ -322,11 +325,21 @@
|
||||
"properties": {
|
||||
"coordinates": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "number"
|
||||
},
|
||||
"minItems": 2,
|
||||
"maxItems": 2
|
||||
"maxItems": 2,
|
||||
"items": [
|
||||
{
|
||||
"type": "number",
|
||||
"minimum": -180,
|
||||
"maximum": 180
|
||||
},
|
||||
{
|
||||
"type": "number",
|
||||
"minimum": -90,
|
||||
"maximum": 90
|
||||
}
|
||||
],
|
||||
"additionalItems": false
|
||||
},
|
||||
"coordinate_system": {
|
||||
"type": "string",
|
||||
|
||||
240
schema.md
240
schema.md
@ -1,8 +1,10 @@
|
||||
# WH Telemetry Protocol Specification
|
||||
|
||||
## 概述
|
||||
|
||||
WH Telemetry Protocol（WHTP）是一套专为物联网场景设计的轻量级、强自描述性遥测数据上行协议，采用 JSON 作为数据承载格式。WHTP 面向传感器数据、遥测采集、边缘网关等设备与云端的数据交互，兼顾数据结构规范、易于解析与灵活拓展，适用于农业、环境监测、工业自动化等多种场景。
|
||||
|
||||
协议设计核心特点：
|
||||
### 核心特点
|
||||
|
||||
- 自描述：字段类型、单位、置信度、枚举、错误信息等全部可内嵌于消息，无需依赖外部 schema 即可独立解析
|
||||
- 结构统一：所有遥测消息采用统一的数据结构，便于前端/平台/存储适配与二次开发
|
||||
@ -11,13 +13,20 @@ WH Telemetry Protocol（WHTP）是一套专为物联网场景设计的轻量级
|
||||
- 可扩展性：预留元数据（metadata）与用户自定义信息（user），支持平台与业务个性化扩展
|
||||
- 错误与置信机制：内建错误码、错误信息与置信度表达，方便数据质量管理与自动化校验
|
||||
|
||||
消息结构总览：
|
||||
### 消息结构总览
|
||||
|
||||
- 根级字段：描述消息身份、设备、时间、环境等全局信息
|
||||
- 字段组（fields）：每个测量项（field）携带唯一 ID、测量值（value）、类型元信息（metadata）
|
||||
|
||||
> [!NOTE]
|
||||
> 本文档假设读者熟悉 [Typescript](https://www.typescriptlang.org/) 类型系统, 以及 [JSON](https://www.json.org/json-en.html) 格式, 并使用 [Typescript](https://www.typescriptlang.org/) 作为伪代码/类型定义语言
|
||||
|
||||
> [!NOTE]
|
||||
> 请配合 [JSON Schema](https://json-schema.org/) 使用 (见 [schema.json](./schema.json)), 以获得更好的类型推导与校验体验
|
||||
|
||||
## 根级字段
|
||||
|
||||
|
||||
| 字段 | 必选 | 类型 | 说明 |
|
||||
| --------- | ---- | --------------- | ---------------------------------------------- |
|
||||
| version | 是 | number | 协议主版本号 |
|
||||
@ -29,32 +38,32 @@ WH Telemetry Protocol（WHTP）是一套专为物联网场景设计的轻量级
|
||||
| fields | 是 | `Field[]` | 采集字段数组 |
|
||||
| metadata | 否 | object | 消息级元数据 |
|
||||
|
||||
### Version (`version`)
|
||||
### 版本
|
||||
|
||||
必填。正整数，仅表示协议主版本号。当前版本为 **1**。
|
||||
`version` 描述协议主版本号, 必填, 其类型为 `number`, 仅表示协议主版本号。当前版本为 **1**。
|
||||
|
||||
### 消息类型 (`msg_type`)
|
||||
### 消息类型
|
||||
|
||||
必填。字符串。目前仅允许 `"telemetry"`，用于上传遥测数据。
|
||||
`msg_type` 描述消息类型, 必填, 其类型为 `string`, 目前仅允许 `"telemetry"`，用于上传遥测数据。
|
||||
|
||||
### 消息模式 (`mode`)
|
||||
### 消息模式
|
||||
|
||||
可选，字符串，默认 `"descriptive"`。
|
||||
`mode` 描述消息模式, 可选, 其类型为 `string`, 默认 `"descriptive"`。
|
||||
|
||||
* `descriptive` —— 自描述模式，允许在字段 `metadata` 中携带全部上下文信息，消息本身即可被独立解析。
|
||||
* `strict` (RFU, reserved for future use) —— 严格模式，不允许出现字段级 `metadata`，字段定义需通过外部文档约定，适用于带宽受限或固定 Schema 场景。(目前无实际意义, 需要与二进制协议配合)
|
||||
|
||||
### 设备 ID (`dev_id`)
|
||||
### 设备ID
|
||||
|
||||
必填。设备唯一标识，采用 [NanoID](https://github.com/ai/nanoid) 格式（如 `2B1oj2S5k7kS8mL_QaCs`），在设备生命周期内保持不变。
|
||||
`dev_id` 描述设备唯一标识, 必填, 其类型为 `string`, 采用 [NanoID](https://github.com/ai/nanoid) 格式（如 `2B1oj2S5k7kS8mL_QaCs`），在设备生命周期内保持不变。
|
||||
|
||||
### 设备类型 (`dev_type`)
|
||||
### 设备类型
|
||||
|
||||
```typescript
|
||||
type DeviceType = string | { type_id: string } | { type_name: string }
|
||||
```
|
||||
|
||||
必选。用于标识设备类别或型号。支持三种写法：
|
||||
`dev_type` 描述设备型号, 必填, 其类型为 `DeviceType`, 用于标识设备类别或型号。支持三种写法：
|
||||
|
||||
1. **字符串**：例如 `"device_type_name"`；与 `{ "type_name": string }` 等价
|
||||
2. **对象** `{ "type_id": NanoID }`；NanoID 为设备型号的唯一标识, 由平台分配
|
||||
@ -67,7 +76,9 @@ type DeviceType = string | { type_id: string } | { type_name: string }
|
||||
> - 对于长期稳定的系统, 推荐使用 `{ "type_id": NanoID }` 格式, 作为稳定的唯一标识符
|
||||
> - 对于临时场景, 可以使用 `string` 或 `{ "type_name": string }` 格式
|
||||
|
||||
### 根级时间戳 (`timestamp`)
|
||||
### 根级时间戳
|
||||
|
||||
`timestamp` 描述消息生成时刻, 其类型为 `Timestamp`
|
||||
|
||||
```typescript
|
||||
type Timestamp =
|
||||
@ -95,14 +106,13 @@ type Timestamp =
|
||||
> [!NOTE]
|
||||
> 根级 (root-level) 时间戳表示消息生成或入队时刻, 字段级 (field-level) 时间戳表示实际数据采样时刻, 应使用字段级时间戳进行所有时间序列分析
|
||||
|
||||
### 消息描述字段组 (`fields`)
|
||||
### 字段描述组
|
||||
|
||||
必填。`Field` 对象数组，数组中每个元素代表一个测量项，其 `id` 在同一条消息内必须唯一。
|
||||
关于 `Field` 对象的定义详见后文 ["消息描述字段"](#%E6%B6%88%E6%81%AF%E6%8F%8F%E8%BF%B0%E5%AD%97%E6%AE%B5) 章节。
|
||||
`fields` 描述消息中包含的测量项, 其类型为 `Field[]`, 数组中每个元素代表一个测量项, 其 `id` 在同一条消息内必须唯一, 关于 `Field` 对象的定义详见后文 [字段描述项](#%E5%AD%97%E6%AE%B5%E6%8F%8F%E8%BF%B0%E9%A1%B9) 章节
|
||||
|
||||
### 消息元数据 (`metadata`)
|
||||
### 根级元数据
|
||||
|
||||
`user` 字段之外的 `metadata` 字段为已定义 (well-defined) 字段, 其定义见下文
|
||||
`metadata` 描述根级 (消息级) 元数据, 其类型为 `MessageMetadata`
|
||||
|
||||
```typescript
|
||||
interface MessageMetadata {
|
||||
@ -114,16 +124,17 @@ interface MessageMetadata {
|
||||
}
|
||||
```
|
||||
|
||||
#### 全局枚举 (`enums`)
|
||||
> [!NOTE]
|
||||
> `user` 字段之外的 `metadata` 字段为已定义 (well-defined) 字段; 用户应优先使用已定义字段, 若不能满足需求才可使用 [用户自定义字段](#%E6%A0%B9%E7%BA%A7%E7%94%A8%E6%88%B7%E8%87%AA%E5%AE%9A%E4%B9%89%E5%AD%97%E6%AE%B5)
|
||||
|
||||
可选。全局枚举定义表，用于在字段 `fields[*].metadata.data_type` 中以 `enum:<id>` 形式引用。
|
||||
#### 全局枚举
|
||||
|
||||
```typescript
|
||||
type InlineEnum = Record<string, number>
|
||||
type EnumDefinition = { id: string; value: InlineEnum };
|
||||
```
|
||||
|
||||
示例
|
||||
`metadata.enums` 字段类型为 `EnumDefinition[]`, 用于在字段 `fields[*].metadata.data_type` 中以 `enum:<id>` 形式引用, 如
|
||||
|
||||
```jsonc
|
||||
"metadata": {
|
||||
@ -138,17 +149,19 @@ type EnumDefinition = { id: string; value: InlineEnum };
|
||||
|
||||
等价于
|
||||
|
||||
```cpp
|
||||
enum class AirQuality {
|
||||
```typescript
|
||||
enum AirQuality {
|
||||
GOOD = 1,
|
||||
MODERATE = 2,
|
||||
BAD = 3,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
#### 位置信息 (`location`)
|
||||
详见 [枚举类型](#%E6%9E%9A%E4%B8%BE%E7%B1%BB%E5%9E%8B)
|
||||
|
||||
可选。表示消息采集时的设备地理位置
|
||||
#### 位置信息
|
||||
|
||||
`metadata.location` 字段类型为 `Location`, 表示消息采集时的设备地理位置, 如
|
||||
|
||||
```typescript
|
||||
type Location = {
|
||||
@ -170,69 +183,117 @@ type Location = {
|
||||
}
|
||||
```
|
||||
|
||||
#### 电量 (`battery`)
|
||||
#### 电量
|
||||
|
||||
可选。数字，范围 0–100，对应设备剩余电量百分比。
|
||||
`metadata.battery` 字段类型为数字, 表示设备剩余电量百分比, 其范围为 0–100
|
||||
|
||||
#### 序列号 (`seq`)
|
||||
#### 序列号
|
||||
|
||||
可选。无符号整数。每上传一条消息递增 1，用于检测丢包或乱序。达到上限后循环计数（默认为 32 位无符号整数回绕）。
|
||||
`metadata.seq` 字段类型为无符号整数, 每上传一条消息递增 1, 用于检测丢包或乱序, 达到上限后循环计数（默认为 32 位无符号整数回绕）
|
||||
|
||||
#### 用户自定义信息 (`user`)
|
||||
#### 根级用户自定义字段
|
||||
|
||||
可选。任意键值对，为数据生产方保留的自定义信息区
|
||||
`metadata.user` 字段为任意键值对, 为数据生产方保留的自定义信息区, 其类型为 `UserData`
|
||||
|
||||
```typescript
|
||||
type UserData = Record<string, any>
|
||||
```
|
||||
|
||||
## 消息描述字段
|
||||
## 字段描述项
|
||||
|
||||
### 标识符 (`id`)
|
||||
每个字段 (field) 描述一个测量项, 其类型为 `Field`
|
||||
|
||||
必填。ASCII 字符串，仅允许字母、数字与下划线，且不得以数字开头。长度建议 1–64 字符。例如 `temperature_sensor`。
|
||||
### 字段标识符
|
||||
|
||||
### 值 (`value`)
|
||||
`id` 描述字段标识符, 必填, 其类型为 `string`, ASCII 字符串，仅允许字母、数字与下划线，且不得以数字开头。长度建议 1–64 字符。例如 `temperature_sensor`。
|
||||
|
||||
字段实际测量值，其类型必须与 `metadata.data_type` 完全对应，形态分三类：
|
||||
### 字段值
|
||||
|
||||
`value` 描述字段值, 其类型必须与 `metadata.data_type` 完全对应, 详见 ["数据类型"](#%E6%95%B0%E6%8D%AE%E7%B1%BB%E5%9E%8B) 章节
|
||||
|
||||
#### 标量 (scalar)
|
||||
|
||||
`string | number | boolean | enum<id>`, 如
|
||||
|
||||
1. **标量** — `string | number | boolean | enum`
|
||||
```jsonc
|
||||
"value": 42
|
||||
{
|
||||
"id": "example_number",
|
||||
"value": 42,
|
||||
"metadata": { "data_type": "number" }
|
||||
}
|
||||
```
|
||||
2. **等间隔数组 (array)** — `T[]`，通过 `sample_interval` 指定采样间隔
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"id": "example_string",
|
||||
"value": "hello",
|
||||
"metadata": { "data_type": "string" }
|
||||
}
|
||||
```
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"id": "example_enum",
|
||||
"value": 1, // interpreted as "good"
|
||||
"metadata": { "data_type": "enum:this", "enum": { "good": 1, "moderate": 2, "bad": 3 } }
|
||||
}
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> 枚举类型 `enum:this` 表示该字段使用内联枚举, 其定义见下文 ["枚举类型"](#%E6%9E%9A%E4%B8%BE%E7%B1%BB%E5%9E%8B) 章节
|
||||
|
||||
#### 等间隔数组 (array)
|
||||
|
||||
`T[]`，通过 `sample_interval` 指定采样间隔, T 为标量类型, 如
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"id": "example_array",
|
||||
"value": [1, 2, 3],
|
||||
"metadata": { "data_type": "array<number>", "sample_interval": 0.5 }
|
||||
}
|
||||
```
|
||||
3. **非等间隔（irregular）** — `{ v: T[], t: Timestamp[] }`
|
||||
|
||||
> [!NOTE]
|
||||
> 强烈建议所有等间隔数组都显式填写 `sample_interval` 字段, 若不填写则默认采样间隔为 1s
|
||||
|
||||
#### 非等间隔（irregular）
|
||||
|
||||
`{ v: T[], t: Timestamp[] }`, T 为标量类型, 如
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"id": "example_irregular",
|
||||
"value": { "v": [1,2,3], "t": [1715145600,1715145601,1715145603] },
|
||||
"metadata": { "data_type": "irregular<number>" }
|
||||
}
|
||||
```
|
||||
`t` 数组必须与 `v` 数组长度相同, 且 `t` 数组中的时间戳必须严格递增, 否则会被视为非法数据
|
||||
|
||||
`null` 与 `undefined` 不被支持，嵌套数组（如 `array<array<number>>`）亦为非法。
|
||||
> [!IMPORTANT]
|
||||
>
|
||||
> - `null` 与 `undefined` 为非法值
|
||||
> - 嵌套数组（如 `array<array<number>>`）为非法类型
|
||||
|
||||
### 元数据 (`metadata`)
|
||||
### 字段级元数据
|
||||
|
||||
field 级字段元数据, 用于描述 `value` 的类型, 采样间隔, 单位, 标签, 置信度, 错误码, 错误信息, 内联枚举, 用户自定义信息等
|
||||
field 级字段元数据, 用于描述 `value` 的类型, 采样间隔, 单位, 标签, 置信度, 错误码, 错误信息, 内联枚举, 用户自定义信息等, 其类型为 `FieldMetadata`
|
||||
|
||||
#### 数据类型 (`data_type`)
|
||||
#### 数据类型
|
||||
|
||||
必填。字符串。用于描述 `value` 的类型。
|
||||
`data_type` 用于描述 `value` 的类型, 其类型为 `DataType`
|
||||
|
||||
```typescript
|
||||
```haskell
|
||||
type DataType =
|
||||
| ScalarType
|
||||
| ArrayType ScalarType
|
||||
| IrregularType ScalarType
|
||||
```
|
||||
|
||||
所有合法的 `data_type` 如下:
|
||||
所有合法的 `data_type` 的值如下:
|
||||
|
||||
```typescript
|
||||
type DataType =
|
||||
type DataTypeLiteral =
|
||||
| "string"
|
||||
| "number"
|
||||
| "boolean"
|
||||
@ -250,12 +311,14 @@ type DataType =
|
||||
| `irregular<enum:this>`
|
||||
```
|
||||
|
||||
- `null` 和 `undefined` 是非法的
|
||||
- 嵌套是非法的
|
||||
> [!IMPORTANT]
|
||||
>
|
||||
> - `null` 与 `undefined` 为非法值
|
||||
> - 嵌套数组（如 `array<array<number>>`）为非法类型
|
||||
|
||||
下面分别介绍各个类型
|
||||
|
||||
##### 原始型別 (`primitive`)
|
||||
##### 原始型別
|
||||
|
||||
协议中的 **原始型别（primitive）** 直接对应于 JSON 支持的基本数据类型。所有字段的最基本取值都必须属于原始型别。
|
||||
|
||||
@ -269,64 +332,64 @@ type PrimitiveType = string | number | boolean
|
||||
- `number`：IEEE-754 双精度浮点数
|
||||
- `boolean`：布尔值，仅允许 true 或 false（不支持 0/1 或字符串）
|
||||
|
||||
##### 枚举类型 (`enums`)
|
||||
##### 枚举类型
|
||||
|
||||
在本协议中，枚举类型本质上是一种特殊的 number 类型。其取值必须限定在一组预先定义的枚举值中。枚举的具体定义可以来源于：
|
||||
在本协议中，枚举类型 (`enum`, [Enumeration](https://en.wikipedia.org/wiki/Enumeration)) 本质上是一种特殊的 number 类型。其取值必须限定在一组预先定义的枚举值中。枚举的具体定义可以来源于:
|
||||
|
||||
- 全局定义：`metadata.enums`（适用于多个字段复用的场景）
|
||||
- 字段内联定义：`fields[*].metadata.enum`（只对当前字段有效）
|
||||
|
||||
每个枚举值都必须对应唯一的数值（number）。在类型系统中，枚举类型可以视为带有标签约束的 number：
|
||||
每个枚举值都必须对应唯一的数值（number）。在类型系统中，枚举类型可以视为带有标签约束的 number:
|
||||
|
||||
```haskell
|
||||
newtype Enum = number
|
||||
```
|
||||
|
||||
##### 标量类型 (`scalar`)
|
||||
##### 标量类型
|
||||
|
||||
标量类型为 `string | number | boolean | Enum` 的统称, 其定义见上文
|
||||
标量类型 (scalar) 为 `string | number | boolean | Enum` 的统称, 其定义见上文
|
||||
|
||||
```haskell
|
||||
```typescript
|
||||
type ScalarType = PrimitiveType | Enum
|
||||
```
|
||||
|
||||
##### 等间隔数组类型 (`array`)
|
||||
##### 等间隔数组类型
|
||||
|
||||
本协议中的数组类型在 `field` 中的含义为 **等采样率** 的数组, 其定义为:
|
||||
本协议中的数组类型在 `field` 中的含义为 **等采样率** 的数组 (array), 其定义为:
|
||||
|
||||
```haskell
|
||||
type ArrayType T = T[] -- array<T>
|
||||
```typescript
|
||||
type ArrayType<T> = T[] // array<T>
|
||||
```
|
||||
|
||||
##### 非等间隔数组类型 (`irregular`)
|
||||
##### 非等间隔数组类型
|
||||
|
||||
本协议中的非等间隔数组类型在 `field` 中的含义为 **非等采样率** 或 **采样率未知** 的数组, 其定义为:
|
||||
|
||||
```haskell
|
||||
type IrregularType T = { v: T[], t: Timestamp[] } -- irregular<T>
|
||||
```typescript
|
||||
type IrregularType<T> = { v: T[], t: Timestamp[] } // irregular<T>
|
||||
```
|
||||
|
||||
`t` 数组必须与 `v` 数组长度相同, 且 `t` 数组中的时间戳必须严格递增, 否则会被视为非法数据
|
||||
|
||||
等间隔数组与非等间隔数组统称为批量 (batch) 数据
|
||||
|
||||
```haskell
|
||||
type BatchType T = ArrayType T | IrregularType T
|
||||
```typescript
|
||||
type BatchType<T> = ArrayType<T> | IrregularType<T>
|
||||
```
|
||||
|
||||
#### field 时间戳 (`timestamp`)
|
||||
#### 字段时间戳
|
||||
|
||||
可选。若不存在则取 `root.timestamp` 的值; 表示该字段 **采样时刻** 的时间戳, 其类型为 `Timestamp`
|
||||
`timestamp` 描述字段时间戳, 可选, 其类型为 `Timestamp`, 若不存在则取 `root.timestamp` 的值; 表示该字段 **采样时刻** 的时间戳
|
||||
|
||||
#### 标签 (`label`)
|
||||
#### 标签
|
||||
|
||||
可选。字段展示名，UTF-8 字符串，便于人机界面直观呈现。实际是否使用/如何使用由数据消费方决定。
|
||||
`label` 描述字段展示名, 可选, 其类型为 `string`, 便于人机界面直观呈现。实际是否使用/如何使用由数据消费方决定。
|
||||
|
||||
示例：`"label": "温度"`
|
||||
|
||||
#### 错误码 (`error_code`)
|
||||
#### 错误码
|
||||
|
||||
可选。非零整数。0 表示无错误；其他值与以下错误码表对应，用于描述测量异常。
|
||||
`error_code` 描述错误码, 可选, 其类型为 `number`, 非零整数。0 表示无错误；其他值与以下错误码表对应，用于描述测量异常。
|
||||
|
||||
| 代码 | 分类 | 名称 | 描述 |
|
||||
| ---------- | ---------- | --------------------- | ------------------------------------------ |
|
||||
@ -349,17 +412,17 @@ type BatchType T = ArrayType T | IrregularType T
|
||||
| 512–1023 | 应用 | — | 留给具体应用 / 产品线自定义 |
|
||||
| 1024–65535 | 厂商自定义 | — | 厂商或项目私有错误码区间 |
|
||||
|
||||
#### 错误信息 (`error_msg`)
|
||||
#### 错误信息
|
||||
|
||||
可选。UTF-8 字符串，对 `error_code` 进行人类可读的补充说明。
|
||||
`error_msg` 描述错误信息, 可选, 其类型为 `string`, 对 `error_code` 进行人类可读的补充说明。
|
||||
|
||||
#### 置信度 (`confidence`)
|
||||
#### 置信度
|
||||
|
||||
```typescript
|
||||
type Confidence = number | number[]
|
||||
```
|
||||
|
||||
置信度用于表征 value 数据的可靠性，其取值类型可为单个数值（`number`）或数值数组（`number[]`），具体规则如下：
|
||||
`confidence` 描述置信度, 可选, 其类型为 `Confidence`, 用于表征 value 数据的可靠性，其取值类型可为单个数值（`number`）或数值数组（`number[]`），具体规则如下：
|
||||
|
||||
- 当 confidence 为单个数值时，表示该字段所有采样点共用相同的置信度。此形式适用于任意类型的 value（包括单点和批量数据）。
|
||||
- 当 confidence 为数值数组时，表示每个采样点各自的置信度。此形式仅适用于批量数据（即 value 为数组或不等间隔序列）；此时 confidence 数组长度必须与采样点数量严格一致。
|
||||
@ -375,9 +438,9 @@ type Confidence = number | number[]
|
||||
> - 如未指定 confidence 字段，则默认所有采样点的置信度为 1
|
||||
|
||||
|
||||
#### 采样间隔 (`sample_interval`)
|
||||
#### 采样间隔
|
||||
|
||||
可选。采样间隔, 用于描述 `value` 为等间隔数组时, 数组中每个元素的时间间隔 (建议所有等间隔数组都显式填写该字段)
|
||||
`sample_interval` 描述采样间隔, 可选, 其类型为 `SampleInterval`, 用于描述 `value` 为等间隔数组时, 数组中每个元素的时间间隔
|
||||
|
||||
```typescript
|
||||
type TimeDelta = { ms?: number, s?: number, m?: number, h?: number, d?: number, w?: number }
|
||||
@ -394,27 +457,26 @@ type SampleInterval =
|
||||
|
||||
示例：`"sample_interval": 0.5`（两次采样间隔 0.5 秒）
|
||||
|
||||
#### 单位 (`unit`)
|
||||
> [!IMPORTANT]
|
||||
> 强烈建议所有等间隔数组都显式填写 `sample_interval` 字段
|
||||
|
||||
可选。测量值单位。推荐使用 [UCUM](https://ucum.org/ucum) 码（如 `"Cel"` 代表摄氏度），也支持自由字符串。
|
||||
#### 单位
|
||||
|
||||
`unit` 描述单位, 可选, 其类型为 `string`, 推荐使用 [UCUM](https://ucum.org/ucum) 码（如 `"Cel"` 代表摄氏度），也支持自由字符串。
|
||||
|
||||
示例：`"unit": "Cel"`
|
||||
|
||||
#### 内联枚举 (`enum`)
|
||||
#### 内联枚举
|
||||
|
||||
可选。当 `data_type` 为 `enum:this` 及其衍生类型时, 用于定义内联枚举值
|
||||
`enum` 描述内联枚举, 可选, 其类型为 `InlineEnum`, 当 `data_type` 为 `enum:this` 及其衍生类型时, 用于定义内联枚举值, 详见 [枚举类型](#%E6%9E%9A%E4%B8%BE%E7%B1%BB%E5%9E%8B)
|
||||
|
||||
```typescript
|
||||
type InlineEnum = Record<string, number>
|
||||
```
|
||||
|
||||
#### 用户自定义信息 (`user`)
|
||||
#### 字段级用户自定义字段
|
||||
|
||||
可选。任意键值对，为数据生产方保留的自定义信息区：
|
||||
|
||||
```typescript
|
||||
type UserData = Record<string, any>
|
||||
```
|
||||
`user` 描述字段级用户自定义字段, 可选, 类型定义同 [根级用户自定义字段](#%E6%A0%B9%E7%BA%A7%E7%94%A8%E6%88%B7%E8%87%AA%E5%AE%9A%E4%B9%89%E5%AD%97%E6%AE%B5)
|
||||
|
||||
## 伪代码类型定义
|
||||
|
||||
|
||||
Reference in New Issue
Block a user