x

2025-07-08 11:06:57 +08:00
parent 03e20a7c87
commit f552dc75f9
3 changed files with 118 additions and 60 deletions
--- a/schema.md
+++ b/schema.md
@ -194,33 +194,78 @@ type UserData = Record<string, any>

 ### 值 (`value`)

-字段实际测量值，其类型必须与 `metadata.data_type` 完全对应，形态分三类：
+字段实际测量值，其类型必须与 `metadata.data_type` 完全对应, 详见 ["数据类型"](#%E6%95%B0%E6%8D%AE%E7%B1%BB%E5%9E%8B) 章节
+
+1. **标量** (scalar)
+
+  `string | number | boolean | enum<id>`, 如
+
+  ```jsonc
+  {
+    "id": "example_number",
+    "value": 42,
+    "metadata": { "data_type": "number" }
+  }
+  ```
+
+  ```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": { "1": "good", "2": "moderate", "3": "bad" } }
+  }
+  ```
+
+  > [!NOTE]
+  > 枚举类型 `enum:this` 表示该字段使用内联枚举, 其定义见下文 ["枚举类型"](#%E6%9E%9A%E4%B8%BE%E7%B1%BB%E5%9E%8B) 章节
+
+2. **等间隔数组 (array)** 
+   `T[]`，通过 `sample_interval` 指定采样间隔, T 为标量类型, 如

-1. **标量** — `string | number | boolean | enum`
   ```jsonc
-   "value": 42
+   {
+    "id": "example_array",
+    "value": [1, 2, 3],
+    "metadata": { "data_type": "array<number>", "sample_interval": 0.5 }
+   }
   ```
-2. **等间隔数组 (array)** — `T[]`，通过 `sample_interval` 指定采样间隔
+
+   > [!NOTE]
+   > 强烈建议所有等间隔数组都显式填写 `sample_interval` 字段, 若不填写则默认采样间隔为 1s
+
+3. **非等间隔（irregular）** 
+
+   `{ v: T[], t: Timestamp[] }`, T 为标量类型, 如
+
   ```jsonc
-   "value": [1, 2, 3],
-   "metadata": { "data_type": "array<number>", "sample_interval": 0.5 }
-   ```
-3. **非等间隔（irregular）** — `{ v: T[], t: Timestamp[] }`
-   ```jsonc
-   "value": { "v": [1,2,3], "t": [1715145600,1715145601,1715145603] },
-   "metadata": { "data_type": "irregular<number>" }
+   {
+    "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
 type DataType = 
@ -255,7 +300,7 @@ type DataType =

 下面分别介绍各个类型

-##### 原始型別 (`primitive`)
+##### 原始型別

 协议中的 **原始型别（primitive）** 直接对应于 JSON 支持的基本数据类型。所有字段的最基本取值都必须属于原始型别。

@ -269,14 +314,14 @@ 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