From f78d95d98dbaf833e351f10bc926e6675b64b789 Mon Sep 17 00:00:00 2001
From: crosstyan <crosstyan@outlook.com>
Date: Tue, 8 Jul 2025 11:41:16 +0800
Subject: [PATCH] Update schema.json ID to point to the raw Git repository;
 enhance schema.md with an overview section and additional notes for better
 clarity and usability of the WH Telemetry Protocol documentation.

---
 schema.json |  2 +-
 schema.md   | 31 +++++++++++++++++++++----------
 2 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/schema.json b/schema.json
index 35f0f7c..ce64321 100644
--- a/schema.json
+++ b/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",
diff --git a/schema.md b/schema.md
index d3a894c..9853255 100644
--- a/schema.md
+++ b/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          | 协议主版本号                                   |
@@ -148,6 +157,8 @@ enum AirQuality {
 }
 ```
 
+详见 [枚举类型](#%E6%9E%9A%E4%B8%BE%E7%B1%BB%E5%9E%8B)
+
 #### 位置信息
 
 `metadata.location` 字段类型为 `Location`, 表示消息采集时的设备地理位置, 如
@@ -336,7 +347,7 @@ newtype Enum = number
 
 标量类型 (scalar) 为 `string | number | boolean | Enum` 的统称, 其定义见上文
 
-```haskell
+```typescript
 type ScalarType = PrimitiveType | Enum
 ```
 
@@ -344,24 +355,24 @@ type ScalarType = PrimitiveType | Enum
 
 本协议中的数组类型在 `field` 中的含义为 **等采样率** 的数组 (array), 其定义为:
 
-```haskell
-type ArrayType T = T[] -- array<T>
+```typescript
+type ArrayType<T> = T[] // array<T>
 ```
 
 ##### 非等间隔数组类型
 
 本协议中的非等间隔数组类型在 `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>
 ```
 
 #### 字段时间戳
@@ -455,7 +466,7 @@ type SampleInterval =
 
 #### 内联枚举
 
-`enum` 描述内联枚举, 可选, 其类型为 `InlineEnum`, 当 `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>