JSON Schema

提供可下载的Observation v1校验定义与有效/缺测样例；设备档案、算法清单和阈值契约仍由各专题说明。

Schema 的作用是让"数据能不能被接受"变成可执行规则，而不是靠文档约定。

必填指标、单位、时间、质量、传感器与来源；unit为机器单位文本。Schema不判断单位是否适合该物理量，业务层必须单独校验。format日期检查需要校验器显式启用。

当前发布Observation v1；新增必填字段或改变状态语义时需升级契约版本并保留迁移记录。缺测必须value=null，有效/修正/插值结果必须为数值。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://siybe.com/assets/schemas/observation.json",
  "title": "SIYB E Observation v1",
  "description": "观测交换示例契约；结构校验之外仍须检查指标单位、测点、时间和方法语义。",
  "type": "object",
  "required": [
    "metric_id",
    "value",
    "unit",
    "observed_at",
    "quality_flag",
    "sensor_id",
    "provenance"
  ],
  "properties": {
    "metric_id": {
      "type": "string",
      "pattern": "^[a-z0-9-]+$"
    },
    "value": {
      "type": [
        "number",
        "null"
      ]
    },
    "unit": {
      "type": "string",
      "minLength": 1
    },
    "observed_at": {
      "type": "string",
      "format": "date-time"
    },
    "quality_flag": {
      "enum": [
        "ok",
        "suspect",
        "invalid",
        "corrected",
        "missing",
        "interpolated"
      ]
    },
    "sensor_id": {
      "type": "string",
      "minLength": 1
    },
    "site_id": {
      "type": "string",
      "minLength": 1
    },
    "raw": {
      "type": "object"
    },
    "provenance": {
      "type": "object",
      "required": [
        "source"
      ],
      "properties": {
        "source": {
          "type": "string",
          "minLength": 1
        },
        "algorithm": {
          "type": [
            "string",
            "null"
          ]
        },
        "calibration": {
          "type": [
            "string",
            "null"
          ]
        },
        "reviewed_at": {
          "type": "string",
          "format": "date"
        }
      }
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "quality_flag": {
            "const": "missing"
          }
        },
        "required": [
          "quality_flag"
        ]
      },
      "then": {
        "properties": {
          "value": {
            "type": "null"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "quality_flag": {
            "enum": [
              "ok",
              "corrected",
              "interpolated"
            ]
          }
        },
        "required": [
          "quality_flag"
        ]
      },
      "then": {
        "properties": {
          "value": {
            "type": "number"
          }
        }
      }
    }
  ]
}

• Observation Schema v1（JSON）
• 有效观测示例（JSON）
• 缺测观测示例（JSON）

先用同一版本Schema检查正常与缺测示例，再检查日期格式、指标单位对应和来源。JSON可解析不等于测量有效；示例均为教学数据。业务层还应拒绝未知指标/不匹配单位并保留原报文。