Refactor field description terminology in schema.md; update section headers and clarify definitions for message fields and types to improve documentation consistency and readability.

This commit is contained in:
2025-07-08 11:29:18 +08:00
parent fa04055e57
commit e66d62ed6a

View File

@ -97,9 +97,9 @@ 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) 章节
### 根级元数据
@ -188,7 +188,9 @@ type Location = {
type UserData = Record<string, any>
```
## 消息描述字段
## 字段描述项
每个字段 (field) 描述一个测量项, 其类型为 `Field`
### 字段标识符
@ -198,7 +200,7 @@ type UserData = Record<string, any>
`value` 描述字段值, 其类型必须与 `metadata.data_type` 完全对应, 详见 ["数据类型"](#%E6%95%B0%E6%8D%AE%E7%B1%BB%E5%9E%8B) 章节
1. **标量** (scalar)
#### 标量 (scalar)
`string | number | boolean | enum<id>`, 如
@ -229,7 +231,8 @@ type UserData = Record<string, any>
> [!NOTE]
> 枚举类型 `enum:this` 表示该字段使用内联枚举, 其定义见下文 ["枚举类型"](#%E6%9E%9A%E4%B8%BE%E7%B1%BB%E5%9E%8B) 章节
2. **等间隔数组 (array)**
#### 等间隔数组 (array)
`T[]`,通过 `sample_interval` 指定采样间隔, T 为标量类型, 如
```jsonc
@ -243,7 +246,7 @@ type UserData = Record<string, any>
> [!NOTE]
> 强烈建议所有等间隔数组都显式填写 `sample_interval` 字段, 若不填写则默认采样间隔为 1s
3. **非等间隔irregular**
#### 非等间隔irregular
`{ v: T[], t: Timestamp[] }`, T 为标量类型, 如