45-EFT.WP.Data.Pipeline v1.0 | 第5章 Schema 与契约管理

目录 ／ 文档-技术白皮书 ／ 45-EFT.WP.Data.Pipeline v1.0

第5章 Schema 与契约管理

I. 章节目的与范围

II. 术语与依赖

• 术语：schema_ref（模式引用）、contract（数据契约）、compat_mode（兼容模式）、evolution_policy（演进策略）、shadow（影子对比）、breaking（破坏性变更）。
• 依赖：数据契约与导出（《Core.DataSpec v1.0》）；单位/量纲校核（《Core.Metrology v1.0》）；切分/覆盖/质量（《DatasetCards v1.0》）；特征与 I/O 假设（《ModelCards v1.0》）。
• 数学与符号：内联符号一律用反引号；含除号/积分/复合算符必须加括号并（如涉路径量）声明 gamma(ell) 与 d ell；公式/符号/定义禁用中文。

III. 字段与结构（规范性）

contract:

schema_ref: "contracts/<name>@vX.Y" # 版本化 Schema 引用（必填）

compat_mode: "forward|backward|both|break"

evolution_policy:

add_field: "optional-by-default|feature-flag"

remove_field: "forbid|deprecate-then-remove"

change_type: "coercible|forbid"

change_sematic: "requires-shadow-and-signoff"

constraints:

primary_key: ["<col1>", "<col2?>"]

partition_by: ["<pcol?>"]

unique: [["<colA>","<colB>"]]

not_null: ["<colX>", "<colY>"]

range:

- {col:"<metric>", rule:"[lo,hi]"}

enum:

- {col:"<status>", values:["A","B","C"]}

units: { "<col>":"<SI-unit>" } # 与计量章一致

validation:

mode: "strict|lenient"

sample: {rows: 10000, strategy:"head|random|stratified"}

significance: {alpha: 0.05}

shadow:

enabled: true

route: "percent:5" # 影子比例或选择器

compare_metrics: ["dq.pass_rate","error_rate","latency_ms.p95"]

lineage_bind:

produce: ["<artifact_path>"]

consume: ["<upstream_schema_ref>"]

IV. 契约注册与发布流程

1. 注册：schema_ref 在模式仓库登记，携带哈希与变更摘要；首次发布需附最小示例与 DQ 基线。
2. 兼容性矩阵：
   • forward：下游能接受上游新增可选字段；
   • backward：上游能输出下游旧字段子集；
   • both：双向兼容；
   • break：破坏性变更，需影子对比与签核。
3. 演进策略：字段新增默认可选；删除采用“弃用→移除”的两阶段；类型变更仅允许 可强制转换（coercible） 场景并附转换规则。
4. 发布门槛：Schema 校验=通过、DQ=通过、影子对比差异在阈内、metrology.check_dim=true、引用锚点齐全。

V. Schema 设计约束

• 显式单位与量纲：数值列必须在 constraints.units 显式 SI 单位；复合量合成前先做单位归一。
• 键与索引：primary_key 不得包含可空列；partition_by 应匹配下游分桶策略；唯一约束需配合去重键。
• 时间与时区：时间列统一 UTC（ISO 8601）；窗口与迟到策略在 validation 说明。
• 枚举与映射：枚举须给出稳定映射与新值接纳策略（unknown|reject|map-to-other）。

VI. 契约影子对比与回滚

• 影子对比：启用 shadow.enabled=true，按 route 分流；对比 dq.pass_rate、错误率与关键性能；超阈触发回滚。
• 回滚策略：compat_mode!="break" 时优先回退上游；break 变更必须提供兼容层或双写窗口。

VII. 机器可读（规范性片段）

layers:

- name: "validate"

stages:

- name: "schema.check"

type: "validate.schema"

impl: "I16-2.schema_check"

inputs: ["raw_rows"]

outputs: ["clean_rows"]

contract:

schema_ref: "contracts/raw_rows@v1.2"

compat_mode: "both"

evolution_policy:

add_field: "optional-by-default"

remove_field: "deprecate-then-remove"

change_type: "coercible"

change_sematic: "requires-shadow-and-signoff"

constraints:

primary_key: ["id"]

not_null: ["id","ts"]

enum: [{col:"status", values:["ok","warn","err"]}]

units: {"lat":"deg","lon":"deg","power_w":"W"}

validation:

mode: "strict"

sample: {rows: 50000, strategy:"stratified"}

significance: {alpha: 0.05}

shadow:

enabled: true

route: "percent:5"

compare_metrics: ["dq.pass_rate","error_rate","latency_ms.p95"]

lineage_bind:

produce: ["lake/clean/2025/09/"]

consume: ["contracts/raw_json@v1.2"]

VIII. Lint 规则（节选，规范性）

lint_rules:

- id: SCHEMA.REF_FORMAT

when: "$..schema_ref"

assert: "matches('^contracts/[a-z0-9_\\-]+@v\\d+\\.\\d+$')"

level: error

- id: SCHEMA.COMPAT_ALLOWED

when: "$..compat_mode"

assert: "value in ['forward','backward','both','break']"

level: error

- id: SCHEMA.UNITS_DECLARED

when: "$..constraints.units"

assert: "all_units_in_SI(value)"

level: error

- id: SCHEMA.PK_NOT_NULL

when: "$..constraints"

assert: "primary_key != null and all_not_null(primary_key, not_null)"

level: error

- id: SCHEMA.SHADOW_REQUIRED_ON_BREAK

when: "$..compat_mode"

assert: "value != 'break' or $.shadow.enabled == true"

level: error

- id: SCHEMA.METROLOGY_CHECKDIM

when: "$.pipeline.metrology"

assert: "units == 'SI' and check_dim == true"

level: error

IX. 契约演进与通知

• 版本命名：严格 @vX.Y；次版本（Y）用于向后兼容新增；主版本（X）用于破坏性变更。
• 通知：对 break 或语义变更（change_sematic）需在 export_manifest.references[] 增加公告锚点并更新下游订阅。
• 迁移期：grace_period 明确起止与双写策略；期内 Lint 降级为 warn，期满恢复为 error。

X. 导出清单与审计轨

export_manifest:

version: "v1.0"

artifacts:

- {path:"contracts/raw_rows.schema.json", sha256:"..."}

- {path:"contracts/changelog.md", sha256:"..."}

- {path:"validate/dq.report.jsonl", sha256:"..."}

- {path:"validate/shadow.diff.csv", sha256:"..."}

references:

- "EFT.WP.Core.DataSpec v1.0:EXPORT"

- "EFT.WP.Core.Metrology v1.0:check_dim"

- "EFT.WP.Data.DatasetCards v1.0:Ch.12"

XI. 本章合规自检

• schema_ref 符合正则并可解析；compat_mode 与 evolution_policy 明确。
• 约束（键/唯一/非空/范围/枚举/单位）完整；units 为 SI 且 check_dim=true。
• 影子对比启用并在阈内；破坏性变更配备兼容层或双写窗口。
• 合同变更已在 export_manifest.references[] 公告；变更工件与 DQ/影子报告具 sha256。
• 下游消费方的 Schema 兼容性与切分/覆盖对齐，通过抽样与显著性检验确认。