Data Contracts 主线——ODCS v3.1.0 精读

日期: 2026-07-01 阶段: P1 - AI 数据产品与知识治理（Day 2/22，D2-3 双日单元上半场） 标签: #data-contracts #odcs #contract-as-code #aml-golden-set

今日导引

• 定位：D2-3 双日单元的上半场，P1 的契约基石。Day 1 论证了「数据侧是主要投资」，但论证不落到可执行工件上就还是口号——契约就是 P1 拿出的第一件工件。今天精读 ODCS v3.1.0（Open Data Contract Standard，Linux Foundation Bitol，2025-12），把规范的区块结构逐块读透，并给本仓 AML 金标数据集起草第一份契约骨架；明天下半场把契约接进 CI。后续 Day 4-5（AI 资产契约）、Day 12-13（版本化）、Day 18（freshness SLA）全部踩在今天的地基上。
• 前置：Day 1 的数据侧论证（尤其 E 节「金标数据集无契约」这条实测缺口）；YAML 与 JSON Schema 的基础读写能力（本仓 dsdb-lab/agent-platform 的配置与 schema 校验代码都用过，不另铺垫）。
• 学完能做什么：能拿到一份 ODCS 契约 YAML 后逐块读懂它约定了什么、缺了哪块会出什么事故；能给一个真实数据集（以本仓 AML 金标为样本）起草 30-50 行的契约骨架，字段名与规范一致；能在被追问「你们不是有 schema 吗」时，说清 contract≠schema——以及它同样不等于 SLA、不等于 catalog。
• 一句话核心：schema 描述数据长什么样，contract 约定生产者和消费者之间谁、以什么质量、什么新鲜度、对什么语义负责——ODCS v3.1.0 把这份约定变成一份可机器校验、可调度执行的 YAML。

衔接

• 昨天：Day 1 用三层证据（Gartner 商业数据 / 模型商品化论证 / 2025-2026 生态并购）立住「数据侧是主要投资」，并钉出 AML Copilot 的三个实测缺口——其中「金标数据集确定性但未版本化、无契约、无血缘」直接指向今天。但「投资数据侧」若只停留在结论，就会退化成买工具、堆文档；投资要落到可执行工件上才可验证。
• 今天：契约就是那个工件。精读 ODCS v3.1.0——为什么需要 data contract（A 节）、为什么标准收敛到 ODCS（B 节）、契约由哪些区块构成（C 节，一手规范核实）、v3.1.0 三个新特性解决什么旧痛点（D 节）、契约如何扩展到 AI 资产（E 节，预告 D4-5）——最后给 AML 金标起草契约骨架（F 节，本篇核心产出）。
• 明天：D3 下半场 contract-as-code——用 datacontract-cli（已切换 ODCS 为默认格式）对今天的契约骨架做 lint 与契约测试，设计进 CI 的契约 gate：schema 漂移、质量规则、可执行 SLA 在 PR 阶段就红。今天不展开 CLI 与 CI 细节。

A. 为什么需要 data contract：接口失配的失败模式

Data contract 解决的问题一句话可说尽：数据的生产者和消费者之间没有接口协议。服务之间早有 OpenAPI/gRPC IDL，改个字段会在编译期或 CI 里炸响；而数据管道之间的「接口」长期靠口头约定、Wiki 文档和「反正一直是这样」。失配时的三种典型失败模式，全部能在本仓 AML 金标数据集上找到具体对应：

1. 结构漂移（最吵闹的一种，也最轻）：producer 改名/改类型/删字段，consumer 直接崩——至少还能看见。更隐蔽的是不崩的改名：本仓 groundTruthEval.ts 的 binaryEval() 以 label !== 'normal' 判定阳性；若某次重构把阴性标签从 'normal' 改成 'benign'，代码一行不崩、测试形状全对，但所有案件被判为阳性——fn=0、tn=0，recall 虚高到 1.0，评测数字整体作废且无人报错。
2. 语义漂移（最危险的一种）：字段名和类型都没变，含义变了。AmlTransaction.amountCents 约定整数分（types.ts 注释明写「禁止 float 金额」）；若未来某个数据源以「元」为单位灌入，类型仍是 number、schema 校验全绿，但 structuring 类型学的 $9,900 边界规则全体失效——v1.1 专门补的 5 个 boundary_9900 难例会齐刷刷判错。这正是 Day 1「静默失败」主题的契约版：schema 管不到语义，只有契约的 description/quality 区块管得到。
3. 供给漂移（SLA 侧）：数据还是那个数据，但没人刷新。金标集若在错误分析后从不补难例（v1→v1.1 做的事），评测会饱和——数字持续全绿，而生产分布早已漂走。这是「过期政策文档」失败链（Day 1 D 节）的金标版。

四个常被混用的工件，边界如下表——先说读表方式：四行不是竞争关系，而是包含与引用关系，contract 把前三者的承诺聚合成一份双方签署、版本化、可执行的协议。

表的关键在最后一列：schema/SLA/catalog 各自只覆盖一个切面且大多不可执行，contract 的增量恰恰是可执行性 + 双边性。对本仓读者最锋利的追问是：「types.ts 不已经是 schema 了吗？」——是，而且是编译期强制的 schema。但它只在同一仓库的编译边界内有效：管不到值域约束（18/15/15/18 的判定分布不是类型能表达的）、管不到新鲜度（类型不知道数据几岁了）、管不到 ownership（git blame 不是责任制），并且在序列化边界（快照落盘、跨进程消费）上彻底消失。TS 类型是契约的 schema 区块的优秀输入，但不是契约。

B. ODCS 是什么，为什么是它

是什么：Open Data Contract Standard，Linux Foundation AI & Data 孵化项目 Bitol 旗下的开放标准，Apache 2.0 许可，用一份 YAML 描述上表第四行的全部内容，配有严格的 JSON Schema 校验文件与 application/odcs+yaml;version=3.1.0 媒体类型（zircote 复盘，2026-04）。当前版本 v3.1.0（2025-12 发布）。

为什么是它——标准之争已收敛。2023-2025 年这个领域有两份并行规范：ODCS 与 datacontract.com 的 Data Contract Specification（DCS）。Day 1 基准表已核实的结局是：随 ODCS v3.1 发布，DCS 团队弃用自家规范、并入 ODCS 生态，迁移支持只到 2026 年底；配套工具 datacontract-cli 已把 ODCS 切为默认格式（zircote，2026-04；datacontract-specification.com 弃用声明）。也就是说 2026-07 学契约只有一条主线可选——这正是本计划黑名单第一条「DCS 作主线」的由来。

采用面（本日核实口径）：Collibra 已提供支持 ODCS 推拉的公开 API，用于接入 dbt/GitHub 等开发流（zircote，2026-04）；OpenMetadata v1.9（2025-08）落地 data contracts、v1.10（2025-10）补齐 SLA/ToS/Security 对象并支持 ODCS 3.1 完整导入导出（OpenMetadata 官方文档）。诚实标注：坊间流传的采用名单常包含 IBM 等更多厂商，本日未能从一手来源核实，本篇不写——口径同 Day 1 弃用 73% 数字的纪律。

C. 契约核心区块精读（一手规范核实，2026-07-01 WebFetch）

ODCS v3.1.0 规范定义 11 个顶层区块（bitol-io.github.io 官方文档，逐页核实）。根级必填字段经 JSON Schema 一手确认为 5 个：version、apiVersion、kind、id、status。下表先给全景，表后对四个承重区块展开——其中 Fundamentals/Schema/Data Quality/SLA 四块的字段名经官方文档逐页核实，References/Support/Pricing/Team/Roles/Servers 五块本篇只到区块级，字段级留待 D3 lint 时按需核：

四个承重区块再各说一点规范细节（都有一手出处）：

• Fundamentals：status 的取值（proposed/draft/active/deprecated/retired）给了契约一个生命周期状态机——这是「契约是活协议、不是归档文档」的规范表达。注意 dataProduct 字段自 v3.1.0 起弃用，数据产品归属另行表达——引用旧教程时要过滤。
• Schema：属性级的 classification（如 confidential/restricted/public）把敏感级下沉到字段——金标的 label 字段该标 restricted（泄漏进被测 prompt 即评测污染）。logicalType/physicalType 分离逻辑与物理类型，正是为了让「integer cents」这类语义约定有处落笔。
• Data Quality：四种 type 是一条从人读到机器执行的光谱——text（人读的期望）→ library（标准 metric，rule 字段已弃用、改用 metric）→ sql（查询结果与 mustBe 系列算子比较）→ custom（引擎特定实现，配 engine/implementation）。加上 severity 与 businessImpact，一条质量规则同时携带「怎么测」和「炸了多严重」。
• SLA：slaProperties 是「property-value 对」的列表（slaDefaultElement 已弃用，v4.0.0 将移除）；driver: regulatory 这个枚举值对金融读者是个信号——规范设计者预期契约会被监管驱动（G 节展开）。

D. v3.1.0 的三个新特性（2025-12，零 breaking change）

Bitol 官方公告的口径是「Stronger, Smarter, and Stricter」，对 v3.0.2 零破坏性变更（Bitol 公告，2025-12）。三个特性各自解决一个明确的旧痛点：

1. 属性间 relationships：relationships 数组同时加在 SchemaObject 与 SchemaProperty 两级（JSON Schema 核实：type 枚举当前仅 foreignKey；对象级需显式 from+to，属性级 from 隐式只写 to；from/to 支持数组表达复合外键）。旧痛点：外键语义此前只活在部落知识和下游 JOIN 代码里——contract 说得清单表却说不清表间关系，跨表一致性检查无处声明。对 AML 数据集：transactions[].accountId → accounts[].id 这类引用完整性，此前只能靠生成器测试自觉维护。
2. 可执行 SLA：RFC-0025 给 slaProperties 加上 scheduler/schedule（如 cron + 0 30 * * *），使 SLA 与质量规则一样可调度执行。旧痛点：v3.0 的一个不对称——quality 早就能执行，SLA 却是纯声明，于是「新鲜度承诺」沦为文档。现在 freshness/retention/frequency 可以像单元测试一样跑（D18 的 freshness SLA、明天的 CI gate 都建立在这上面）。
3. 更严格的 JSON Schema 校验：只允许合法字段，杜绝「宽松多余项」。旧痛点：此前拼错 slaProperties 为 slaProperites 会被静默接受——契约本身成了没有契约保护的数据。这是元层面的自洽：关于数据的契约，自己先要过严格校验。配套还有增强元数据（customProperties 与 authoritativeDefinitions 均新增 description 字段）。

零 breaking change 值得单独一提：对照 DCS 直接弃用的命运，ODCS 用「v3.0.2 契约在 v3.1.0 下继续合法」换取了存量迁移的零成本——标准之争的胜负手一半在治理姿态。

E. 契约扩展到 AI 资产（D4-5 预告，先立框架）

传统契约的对象是表和列；2026 年的治理口径已把对象扩展到 AI 资产——Day 1 已引 Gartner 数据治理平台 MQ 转向非结构化数据与 AI 资产（2026-04），计划基准表另锚定 Gartner 2026-03 的 policy-as-code 方向（契约从数据表延伸到 agent 执行契约，D4-5 主线）。为什么 eval 集/embedding/prompt 也该有契约？因为 A 节三种失败模式在 AI 资产上全部存在且更隐蔽，但漂移语义、版本触发器、provenance 三个维度与表契约不同：

表下补一句边界：本篇只立框架，AI 资产契约的完整处理（含 embedding 契约的字段设计、prompt 契约与 eval 的绑定）是 Day 4-5 的正文，届时 F 节这份骨架会被扩展成 AML eval 数据集的完整契约草案。

F. 实战：AML 金标数据集的 ODCS 契约骨架

对象与事实先摆齐（均来自本仓代码，非虚构）：src/aml/generator.ts 以 seed aipa-golden-v1 确定性生成金标 v1（66 案 = structuring 18 / layering 15 / mule_network 15 / normal 18），以独立 seed aipa-golden-v11 生成 v1.1（同结构 66 案 + 14 难例 = 80 案；难例 = boundary_9900×5 全标 structuring、long_chain_layering×5 与 mixed_struct_layer×4 全标 layering，故 v1.1 分布 = 23/24/15/18）；两版均模块级 memoize；groundTruthEval.ts 以 {label, predicted} 消费并算 recall/precision/FPR + bootstrap CI。schema 区块的字段即 types.ts 的 AmlCase 全部 8 个字段（id/label/subjectPartyId/parties/accounts/transactions/alertReason/windowDays）。

契约骨架（50 行；字段名全部经 C 节一手核实，规范未核实处以注释标注）：

apiVersion: v3.1.0
kind: DataContract
id: aml-golden-eval-dataset
version: 1.1.0            # 绑定代码金标 v1.1（66 基线 + 14 难例 = 80 案）
status: draft             # D3 契约测试进 CI 后转 active
description:
  purpose: AML 类型学判定与 SAR 流水线的评测金标（ground truth），由 src/aml/groundTruthEval.ts 消费
  limitations: 合成数据（seeded PRNG）；判定分布是评测设计值，禁止外推生产误报率
  usage: eval 回归与 CI gate；任何公开 eval 数字必须声明所依据的本契约 version
schema:
  - name: aml_case
    physicalName: AmlCase (src/aml/types.ts)
    logicalType: object
    physicalType: file    # 以 D12-13 落盘快照 golden_YYYY_MM 为准；当前诚实状态是 TS 模块内存对象
    dataGranularityDescription: 一行 = 一个调查案件，内嵌 90 天分析窗口（windowDays=90）内全部交易
    properties:
      - { name: id, logicalType: string, required: true, unique: true, primaryKey: true }
      - name: label
        logicalType: string
        required: true
        description: 金标标签 structuring|layering|mule_network|normal —— eval 的 ground truth
        classification: restricted    # 泄漏进被测 prompt = 评测污染
      - name: subjectPartyId
        logicalType: string
        relationships: [{ to: aml_case.parties.id }]  # v3.1.0 属性级关系（from 隐式）；嵌套路径写法明天用 lint 验证
      - { name: parties, logicalType: array, required: true }
      - { name: accounts, logicalType: array, required: true }
      - { name: transactions, logicalType: array, description: amountCents 恒为整数分——类型学阈值规则的语义地基 }
      - { name: alertReason, logicalType: string, required: true }
      - { name: windowDays, logicalType: integer, required: true }
    quality:
      - name: case-count-v11
        description: v1.1 案件总数恒为 80；漂移 = 金标被未版本化地修改
        type: sql
        query: SELECT COUNT(*) FROM aml_case
        mustBe: 80
        businessImpact: eval 数字与数据版本脱钩，审计不可复现
      - name: normal-share
        description: 阴性案 label='normal' 恒为 18 —— 判定分布是评测设计的一部分（A 节失败模式 1 的断言）
        type: sql
        query: SELECT COUNT(*) FROM aml_case WHERE label = 'normal'
        mustBe: 18
slaProperties:
  - property: frequency   # 金标刷新复核周期：错误分析驱动，复核上限 30 天一次
    value: 30
    unit: d
    scheduler: cron       # v3.1.0 可执行 SLA：明天 D3 起由 CI 调度执行本契约的 quality + SLA 检查
    schedule: '0 6 1 * *'
customProperties:
  - { property: generatorSeed, value: aipa-golden-v11, description: provenance 锚点——seed+生成器代码版本即完整血缘 }

逐块讲这份骨架买到了什么：Fundamentals 把「eval 数字 ↔ 数据版本」绑定问题（Day 1 E 节缺口②）变成 version: 1.1.0 一行——今后任何 eval 报告引用本契约版本即完成声明；description.limitations 把「合成数据禁止外推误报率」从代码注释升格为消费条款。Schema 覆盖 AmlCase 全部 8 个字段，其中 label 的 classification 和 transactions 的整数分语义是两处「schema 表达不了、契约表达得了」的示范。两条 quality 规则直接断言 A 节失败模式 1（分布被静默改动）——注意它们断言的是值而非结构，这正是 quality 区块相对 TS 类型的增量。SLA 的 frequency + scheduler 用上 v3.1.0 可执行 SLA，防的是失败模式 3（金标饱和）。customProperties 记下 seed，配合 git 版本即 E 节说的合成数据双坐标血缘。尚未买到的：team/roles 的 ownership 区块（字段名今天未核实，D3 lint 后补）、落盘快照（D12-13）、以及最重要的——这份 YAML 现在还只是文档，明天它接进 CI 才成为契约。

G. 金融零售视角补注：契约即审计证据

契约在监管语境的价值，用一个真实问询场景就能立住：监管检查问「这份 SAR 的判定依据的数据从哪来、谁对它的质量负责、多久刷新一次」。没有契约的回答是组织考古（翻 Wiki、问离职员工）；有契约的回答是出示一份带版本、带 owner、带可执行质量规则与 SLA 执行记录的 YAML——契约即证据（contract as evidence）。这个思路的监管原型是 BCBS 239《有效风险数据聚合与风险报告原则》（2013-01，打底经典）：它要求银行对风险数据的准确性、完整性、及时性建立可问责的治理——data contract 恰好是这套要求的机器可读形态：schema+quality 对应准确完整、slaProperties 对应及时、team/roles 对应问责。ODCS 把 driver: regulatory 做进 SLA 枚举，说明标准设计者与监管语境的这层对应是有意为之。对 10 年金融零售 BA 背景的读者，这延续 Day 1 D+ 节的判断：契约工作的一半是把口头跨团队约定写成可执行接口——BA 做了十年的事，产物从 Word 换成了带 CI 的 YAML。

深读池链接

• docs/ai-foundations/papers/45-data-lineage-contracts-openlineage-ai-data-quality.md — 血缘与契约的论文级基础，本篇 F 节 provenance 锚点的理论底
• docs/AI_DATA_CONTRACTS_LINEAGE_QUALITY_PLAYBOOK.md — 契约/血缘/质量三件套操作手册，D2-5 的库内总纲
• docs/AI_DATA_PRODUCT_MANAGEMENT_PLAYBOOK.md — 数据产品管理全景，契约在 C9 能力面中的位置
• docs/AI_DATA_LIFECYCLE_GOVERNANCE_PROVENANCE_RETENTION_PLAYBOOK.md — 生命周期与留存治理，G 节审计视角的展开
• docs/AI_REGULATORY_RESPONSE_PLAYBOOK.md — 监管问询应对，G 节「契约即证据」的场景库
• docs/abpa/templates/07-data-readiness-pack.md — D6-7 要实填的 readiness pack，契约是其中数据清单的供给方
• docs/aiprod/day1-data-side-investment.md — 昨天的论证与三个实测缺口，本篇的问题来源

参考资料

1. Bitol / ODCS 官方规范 v3.1.0（bitol-io.github.io/open-data-contract-standard/latest，2025-12 发布；本日 2026-07-01 WebFetch 逐页核实 Fundamentals / Schema / Data Quality / Service-Level Agreement 四节全部字段名与枚举值）
2. ODCS v3.1.0 JSON Schema（github.com/bitol-io/open-data-contract-standard, schema/odcs-json-schema-v3.1.0.json，2025-12；本日 WebFetch 一手核实：根级必填 5 字段、CustomProperty 的 property/value/description、Relationship 的 type=foreignKey 与对象级 from+to / 属性级仅 to 两种形态）
3. Bitol — Bitol Announces ODCS v3.1.0: Stronger, Smarter, and Stricter（bitol.io，2025-12；本日 WebSearch 核实）：relationships / 可执行 SLA（RFC-0025）/ 严格 JSON Schema 校验 / 增强元数据，对 v3.0.2 零 breaking change；Linux Foundation AI & Data 孵化项目，Apache 2.0
4. zircote — Most Data Contract Tools Don't Enforce Contracts: Here's What Does（2026-04；本日 WebSearch 核实）：DCS 随 ODCS v3.1 弃用、迁移支持到 2026 年底；datacontract-cli 切换 ODCS 为默认格式；application/odcs+yaml;version=3.1.0 媒体类型；Collibra 已承诺 ODCS
5. OpenMetadata 官方文档 — Data Contracts Guide（docs.open-metadata.org；v1.9 2025-08 落地 data contracts，v1.10 2025-10 补 SLA/ToS/Security 并支持 ODCS 3.1 完整导入导出；本日 WebSearch 核实）
6. Collibra — 产品文档与博客：支持 ODCS 推拉的公开 API 接入 dbt/GitHub 开发流（发布月份未单独核实，采用事实以引文 4 的 2026-04 口径为准）
7. BCBS — Principles for effective risk data aggregation and risk reporting（BCBS 239，2013-01；打底经典，非主线时效资料——用于 G 节监管问责语境）
8. Gartner — 数据治理平台 MQ 转向非结构化数据与 AI 资产（2026-04，Day 1 已引）；policy-as-code 方向预测（2026-03，docs/AIPROD_90_PLAN.md 基准表锚点，D4-5 展开）
9. docs/AIPROD_90_PLAN.md 第 1 节基准资料表（2026-07-01 核实）：ODCS v3.1.0 事实标准地位、datacontract.com 并入生态仅支持到 2026 底
10. 本仓物证：src/aml/types.ts（AmlCase 8 字段定义）、src/aml/generator.ts（GOLDEN_SEED/GOLDEN_V11_SEED、GOLDEN_COUNTS 18/15/15/18、难例配方 5+5+4、模块级 memoize）、src/aml/groundTruthEval.ts（binaryEval 以 label!=='normal' 判阳性 + bootstrap CI）

SOTA 检查 (2026-07-01)

• 版本状态：ODCS v3.1.0（2025-12）是本日官方文档 latest 指向的现行版本，距今约 7 个月，无更新版本发布迹象。但规范内已埋 v4.0.0 信号——slaDefaultElement、dataProduct、quality.rule 三处标注弃用且注明 v4.0.0 移除——D22（P1 收敛日）与 D90 需查 v4 RFC 动向；若 v4 发布，本篇 C/F 节字段表需复核。
• 竞争规范状态：DCS（datacontract.com）已弃用并入 ODCS 生态，迁移支持硬日期 2026-12 截止。本仓无 DCS 格式存量、无迁移负担；但 2026 年内引用的外部教程/样例若为 DCS 格式，需按黑名单降为历史对照。
• 数字诚信记录：厂商采用名单本篇只写核实到的 Collibra（2026-04 口径）与 OpenMetadata（官方文档，2025-08/10）；坊间流传的 IBM 等其余采用者本日未核实到一手来源，弃用不写。relationships 嵌套路径（aml_case.parties.id）的表示法规范未明示，F 节已标注待 D3 datacontract-cli lint 验证——lint 不过则改为对象级 from/to 或拆平快照后再表达。
• 黑名单自查：本篇未以 DCS 作主线（仅作收敛史实）、未引用 v3.1.0 之前的旧字段教程（dataProduct/rule/slaDefaultElement 均已标注弃用）、契约样例未虚构任何字段名（全部经引文 1/2 一手核实）。
• 下次复查点：明天 D3 用 datacontract-cli 对 F 节骨架做 lint 即是对本篇字段准确性的机器复核；D22 复查 ODCS v4 动向与 OpenMetadata/Collibra 集成状态；2026-12 前确认无 DCS 遗留依赖。