52-数据集卡 Template v1.0 | 第4章 结构与 Schema（字段/单位/量纲）

目录 ／ 文档-技术白皮书 ／ 52-数据集卡 Template v1.0

第4章 结构与 Schema（字段/单位/量纲）

I. 目的与范围（Purpose & Scope）

• 规范数据集**结构（Structure）与数据契约（Schema/Contract）**的编制、校验与发布口径，确保字段、类型、单位与量纲的可追溯与可审计。
• 涉及路径量（到达时/相位）时，正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；发布要求 p_dim = 1.0 并随附 check_dim_report.json。

II. 输入与依赖（Inputs & Dependencies）

• 契约基线：schema.json 与 contract.yaml；与 TARR（数据规范）一致。
• 引用与版本：一律“卷名 + 版本 + 锚点（P/S/M/I）”，锚点直指率 ≥ 90%。
• 计量与参数：与《误差预算卡》协方差/覆盖配置、《参数注册卡》版本/新鲜度策略对齐。

III. 字段表（最小模板，字段/单位/量纲）

强制写法：含除号/积分/复合算符的表达必须加括号；路径阵列满足 len(gamma_ell)=len(d_ell)=len(n_eff)≥2。

IV. 路径量统一口径（Normative Path Forms）

• 到达时（两种等价）：
  T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )；T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
• 相位累计：
  Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell )。

正文显式 gamma(ell) 与 d ell；数据侧记录 delta_form（general|factored）。

V. Schema 规则（缺失/枚举/一致性）

• 缺失策略：数值缺失用 null 或缺字段；禁止文本 NaN/Inf；原因写入 quality.flags。
• 枚举约束：instrument.mode、clock_state 等用 enum 声明；互斥/依赖在 constraints 显式编码。
• 一致性：边传输时两端 Schema（字段/单位/量纲）一致或给出显式映射；禁止隐式单位换算。

VI. 量纲与覆盖（Units & Dimensions / Coverage）

• SI/国际符号统一（m, s, rad, 1, m/s, 1/m, Pa, N, J, Hz）。
• 发布前通过 I70-dim_check，p_dim = 1.0；随附 check_dim_report.json。
• 覆盖口径在数据与发布侧保持一致：coverage.mode ∈ {k, alpha, quantile}。

VII. 机读契约（Machine-Readable Contracts，节选）
A. schema.json

{

"$schema":"https://json-schema.org/draft/2020-12/schema",

"title":"Dataset v1.0.0 (structure)",

"type":"object",

"required":["record_id","acq","path","medium","ref","see","version"],

"properties":{

"record_id":{"type":"string"},

"acq":{"type":"object","required":["ts_start","ts_end"],

"properties":{"ts_start":{"type":"string","format":"date-time"},"ts_end":{"type":"string","format":"date-time"}}},

"instrument":{"type":"object","properties":{"id":{"type":"string"},"mode":{"type":"string"}}},

"path":{"type":"object","required":["gamma_ell","d_ell"],

"properties":{"gamma_ell":{"type":"array","items":{"type":"number"},"minItems":2},

"d_ell":{"type":"array","items":{"type":"number"},"minItems":2}}},

"medium":{"type":"object","required":["n_eff_profile"],

"properties":{"n_eff_profile":{"type":"array","items":{"type":"number"},"minItems":2}}},

"ref":{"type":"object","properties":{"c_ref":{"type":"number"},"lambda_ref":{"type":"number"}}},

"see":{"type":"array","items":{"type":"string"},"minItems":1},

"version":{"type":"string"}

}

}

B. contract.yaml

version: "1.0.0"

units:

T_arr: "s"

Phi: "rad"

c_ref: "m/s"

lambda_ref: "m"

path:

required: true

gamma: "gamma(ell)"

measure: "d ell"

delta_form: "general" # or "factored"

constraints:

enum:

clock_state: ["locked","holdover","free"]

mutex:

- of: ["locked","free"]

rule: "not_both"

missing:

numeric: "null"

reason_to: "quality.flags"

coverage:

mode: "k" # k | alpha | quantile

k: 2

VIII. 质量门与校验（Gates & Validation）

• G1｜Schema 完整：字段、类型、索引/窗口一致；契约/数据对齐。
• G3｜路径规范：gamma/measure/delta_form 齐备；len(path)≥2；Δell ≤ ( c_ref / f_s ) / max(n_eff)。
• G4｜量纲闭合：I70-dim_check 通过，p_dim = 1.0。
• G6｜覆盖口径：coverage.mode ∈ {k, alpha, quantile} 与发布一致。
• 停止（S1–S5）：量纲失败/路径缺失/引用不合规等即拒收并阻断发布；必要时标注 [Restricted]。

IX. 反例与修正（Anti-Patterns & Fixes）

• 反例：T_arr = ∫ n_eff / c_ref d ell（缺括号） → 修正：T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
• 反例：仅声明 gamma(ell) 未给 d ell/delta_form → 修正：补齐并与 n_eff 对齐。
• 反例：单位用 % 文本 → 修正：单位用 1，在注释说明“百分比”。
• 反例：入库 Schema 与契约不一致 → 修正：同步 schema.json/contract.yaml 并回填数据。

X. 交叉引用（Cross-References）

• 来源与血缘：见第3章；切分与版本：见第6章；质量门与完整性：见第7章；不确定度与协方差：见第8章。
• 与《管线卡》：入站契约（Ch.4）、阶段控制式（Ch.6）。
• 与《误差预算卡》：协方差与传播（Ch.5/Ch.6）、区间与口径（Ch.8）。

XI. 执行勾选清单（Checklist）

• schema.json/contract.yaml 完整一致，字段表单位与量纲齐全。
• 路径量显式 gamma(ell)/d ell，记录 delta_form；len(path) ≥ 2、Δell 合规。
• 到达时/相位采用括号化统一口径；I70-dim_check 通过、p_dim = 1.0。
• coverage.mode 与发布侧一致；see[]/references[]/version 合规且锚点直指率 ≥ 90%。
• /validate 通过 G1/G3/G4/G6；反例项已修正或按规则标注 [Restricted]。