SEO / GEO 数据治理与规范标准细则（八）：Data Contract——如何让数据在进入系统之前，就知道必须遵守哪些规则？

系列专题：SEO / GEO 数据治理与规范标准细则

本篇主题：Data Contract / 数据契约与生产前质量控制

发布日期：2026年10月19日

核心关键词：Data Producer、Data Consumer、Schema、Semantic Contract、Breaking Change、Version Compatibility、Contract Testing、CI/CD、Data Quality Gate

一家工业设备企业更新了自己的产品数据系统。

工程部门已经批准新版本的技术规范。产品参数具有明确的Source of Truth，关键字段都有Data Owner，来源与变更过程也可以追溯。

企业还按照第七篇的方法，为产品数据增加了质量检查。

现在，技术部门希望进一步优化数据结构。

原本用于保存设备额定功率的字段叫：

rated_power_kw

新系统开发人员认为，可以把它统一改成：

power

从程序设计的角度看，这似乎只是一次字段命名调整。

工程数据仍然正确。数据库没有丢失记录。API也能够正常返回结果。

然而，更新上线以后，问题开始出现。

PIM的数据导入程序仍然读取rated_power_kw。

WordPress的产品参数组件无法获取功率。

自动生成的技术PDF缺失了对应字段。

部分Schema生成逻辑继续使用旧数据。

AI知识库的数据同步程序也出现异常。

企业的数据没有突然变得不准确。

真正发生的是：

数据生产者改变了输出方式，却没有确认依赖这些数据的消费者是否能够继续正常工作。

从数据治理的角度，这是一种典型的：

Data Contract Violation。

过去，企业通常在系统出错以后才发现这些问题。

一个字段被删除，几个部门分别报错。

一个单位发生变化，报价系统得到错误结果。

一个事件名称被修改，营销转化数据突然中断。

到了第八篇，我们需要建立一种不同的工作方式：

数据生产者在修改数据之前，就必须知道自己对下游消费者承担什么义务；数据消费者在接收数据之前，也必须能够验证上游是否遵守约定。

这就是Data Contract要解决的核心问题。

一、Data Contract不是另一个数据质量检查表

第七篇讨论了Data Quality。

我们已经能够定义Accuracy、Completeness、Consistency、Validity等质量维度，并建立Quality Rule、Threshold和Admission Gate。

那么为什么还需要Data Contract？

因为数据质量检查通常回答：

“这份数据是否符合质量要求？”

而Data Contract需要进一步回答：

“上游承诺向下游交付什么样的数据，以及发生变化时双方必须遵守什么规则？”

这两个问题密切相关，但并不相同。

假设：

Producer:
Engineering Data Service

Consumer:
PIM
WordPress
PDF Generator
RAG Pipeline

上游系统可能通过了自己的所有质量检查。

但如果它突然删除一个字段，消费者仍然可能无法继续运行。

因此：

Producer Data Quality Pass，不代表Consumer Compatibility Pass。

Data Contract的核心不只是验证单条记录，而是为数据生产者和使用者建立一个稳定、可执行、可变更管理的交付约定。

我们可以将它理解为：

A verifiable agreement between data producers and data consumers.

即：

生产者与消费者之间可以被验证的数据交付契约。

这里所说的Contract主要是数据工程和系统协作中的技术与治理约定，不必然构成法律意义上的商业合同。

二、为什么Data Contract会成为数据治理的重要组成部分？

随着企业数字化系统增加，同一份数据可能被多个部门反复使用。

工程数据进入PIM。

PIM将产品信息传递给网站。

网站将数据转换成HTML和Structured Data。

销售系统使用同一份参数制作报价。

AI系统将企业资料加工为可检索知识。

在这种环境下，数据生产者未必知道所有消费者的具体实现。

消费者也未必能够控制上游的数据结构。

双方之间形成一种依赖关系：

Data Producer
      ↓
Shared Data Interface
      ↓
Data Consumer A
Data Consumer B
Data Consumer C

如果缺少约定，上游系统的一次小改动就可能造成下游大范围故障。

dbt官方的Model Contracts文档提供了一个具有代表性的工程实践：开发者可以预先定义模型应输出的列名、数据类型及受支持的约束；在启用Contract Enforcement后，构建过程会检查模型输出是否符合约定，不符合时构建失败。

这使数据结构的异常能够在模型交付过程中被发现，而不是等待下游系统运行出错。

官方参考：dbt — Model Contracts

Data Contract的核心价值正在于此：

把原本发生在生产环境中的兼容性问题，尽可能提前到设计、开发、测试和部署阶段。

三、Data Contract究竟应该包含什么？

一份成熟的数据契约不应该只有字段名称和数据类型。

至少需要明确五类内容。

契约层	核心内容	回答的问题
Identity & Ownership	契约ID、Producer、Consumer、Owner	谁提供、谁使用、谁负责？
Schema Contract	字段、类型、必填性、结构	交付的数据长什么样？
Semantic Contract	定义、单位、Context、口径	每个字段究竟是什么意思？
Quality & SLA	质量规则、更新频率、可用性要求	达到什么条件才允许交付？
Change & Compatibility	版本、兼容规则、通知和迁移	数据发生变化以后怎么办？

这五类信息共同决定数据能否可靠地在系统之间传递。

它们并非本系列凭空提出的方向。

由Bitol维护的Open Data Contract Standard（ODCS）已经为数据契约提供开放的描述结构，涉及Schema、Data Quality、团队角色、服务等级、基础设施与权威定义等信息。

其官方仓库目前提供ODCS v3.2.0版本。

官方参考：Open Data Contract Standard

但本文接下来提出的具体字段、质量门禁和审批流程，是面向SEO/GEO业务设计的工程实施模型，并非直接复制ODCS官方Schema。

四、首先明确Data Producer与Data Consumer

这是Data Contract能够落地的前提。

Producer不是简单的“数据录入人员”

Data Producer指向下游提供某项数据产品、数据流或数据接口的责任主体。

它可能是：

PLM数据服务。

ERP数据服务。

PIM接口。

CRM数据管道。

GA4事件采集系统。

经过治理的知识数据服务。

Producer需要对交付的数据承担明确义务。

例如：按约定输出字段、遵守字段定义、提供必要的版本信息、满足质量规则、按照规定通知Breaking Change，不能未经协调随意改变已经对外承诺的数据含义。

Consumer不是简单的“拥有读取权限的人”

Data Consumer是依赖数据完成业务处理的系统、部门或程序。

例如：WordPress产品页面、报价生成器、Looker Studio数据集、PDF生成程序、AI知识库同步任务、RAG问答服务。

Consumer也有自己的责任。

它应当明确声明自己依赖哪些字段、格式、版本和语义。

不能把未在契约中承诺的内部字段，当成可以永久依赖的接口。

不能假设每个字段永远不会变化。

也应该在上游通知变更时完成必要的兼容性验证。

因此：

Data Contract不是Producer单方面发布的一份字段说明书，而是生产者和消费者共同维护的依赖约定。

五、回到82 kW案例：为什么字段名称不能随意修改？

继续使用前七篇的演示案例。

某设备在标准50Hz配置下，已批准的额定功率为82 kW。

原始接口：

{
  "product_id": "FW-30",
  "configuration_id": "standard_50hz",
  "rated_power_kw": 82
}

PIM读取：rated_power_kw。

WordPress也读取：rated_power_kw。

后来Producer将接口修改成：

{
  "product_id": "FW-30",
  "configuration_id": "standard_50hz",
  "power": 82
}

数值仍然是82。

但对于依赖rated_power_kw的Consumer，这次变化可能是Breaking Change。

更严重的是，power这个新名称还丢失了两个重要语义：

它到底是Rated Power还是Peak Power？

数值单位到底是kW还是W？

原来的字段虽然不完美，但至少提供了较明确的业务含义。

所以企业不能只关注数据转换以后数值有没有变化。

还必须保证：

字段名称、数据类型、业务含义和使用上下文能够保持约定的一致性。

这就是Semantic Contract的重要性。

六、Schema Contract：数据结构应该怎样定义？

Schema Contract是最容易自动化的部分。

它规定：哪些字段必须存在、字段允许使用什么类型、是否允许Null、字段是否具有取值范围、是否允许额外属性、数据对象之间如何嵌套、哪些值必须符合规定格式。

对于JSON接口，可以使用JSON Schema。

JSON Schema Draft 2020-12提供了type、required、properties、exclusiveMinimum等关键字，可以声明并验证JSON数据结构。

官方参考：JSON Schema Draft 2020-12

下面是一份简化的产品事实Schema。

文件名：contracts/product-fact.v1.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Approved Product Fact v1",
  "type": "object",
  "required": [
    "product_id",
    "configuration_id",
    "rated_power_kw",
    "spec_version",
    "effective_from",
    "source_id",
    "evidence_id"
  ],
  "properties": {
    "product_id": {
      "type": "string",
      "minLength": 1
    },
    "configuration_id": {
      "type": "string",
      "minLength": 1
    },
    "rated_power_kw": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "spec_version": {
      "type": "string",
      "minLength": 1
    },
    "effective_from": {
      "type": "string",
      "format": "date"
    },
    "source_id": {
      "type": "string",
      "minLength": 1
    },
    "evidence_id": {
      "type": "string",
      "minLength": 1
    }
  },
  "additionalProperties": false
}

对于对应的数据实例：

{
  "product_id": "FW-30",
  "configuration_id": "standard_50hz",
  "rated_power_kw": 82,
  "spec_version": "4.2",
  "effective_from": "2026-09-20",
  "source_id": "PLM-008",
  "evidence_id": "EV-4201"
}

结构校验可以确认：必填字段是否存在、功率是不是数字、功率是否大于零、Source ID和Evidence ID是否缺失、是否出现契约未声明的额外字段。

这些都可以在数据正式进入PIM之前检测。

但必须注意两个技术边界。

第一，JSON Schema不能仅凭字段结构判断82 kW是否为正确的工程事实。

事实核验仍然需要连接第三篇的Source of Truth与第七篇的数据质量规则。

第二，JSON Schema Draft 2020-12中的format默认可能只是注释性信息。

如果需要严格检查date等格式，必须采用支持相应格式断言的验证器及配置。

因此，部署Schema之前，不仅要审核Schema本身，也要确认执行引擎支持哪些验证能力。

七、Schema正确，仍然可能发生Semantic Breaking Change

这是第八篇特别需要强调的一点。

假设Producer保留字段名称rated_power_kw，但将其业务定义从“标准配置额定功率”修改为“设备最大瞬时功率”。

字段名称没有变化，数据类型仍然是Number，数值范围仍然大于零。

JSON Schema仍然可能验证通过。

但是下游业务已经发生严重偏移。

如果WordPress将新的数值继续标记成Rated Power，内容就可能变得不准确。

如果销售系统根据这个字段计算设备配置，业务结果也可能出错。

因此：

Schema Compatibility不等于Semantic Compatibility。

企业至少应该在Semantic Contract中明确：字段业务定义、单位及换算规则、配置与地区Context、数据粒度、统计或计算方法、来源Authority、生效规则、允许的用途。

对于关键数据，任何改变这些语义的行为，都应进入正式变更审查。

即使技术Schema没有变化。

八、建立完整的SEO/GEO Data Contract Record

Schema解决结构问题，但还缺少责任、质量、使用和变更约定。

企业可以建立一份更完整的契约登记文件。

下面是一份本系列设计的简化YAML示例。

它是内部工程模板，不声称符合ODCS v3.2.0的完整规范结构。若需要跨平台标准化交换，应另行按照ODCS官方Schema实现和验证。

contract_id: DC-PRODUCT-FACT-001
contract_version: 1.0.0

name: Approved Product Facts

producer:
  domain: Engineering
  service: Product Data Service
  owner_role: Engineering Data Owner

consumers:
  - PIM
  - WordPress
  - PDF Generator
  - RAG Ingestion

schema:
  format: json-schema
  reference: product-fact.v1.schema.json

semantics:
  rated_power_kw:
    meaning: Approved rated power
    unit: kW
    context_required: true
    authority: PLM

quality:
  - rule: required_fields_present
    severity: critical

  - rule: canonical_consistency
    severity: critical

  - rule: evidence_verified
    severity: critical

delivery:
  trigger: approved_engineering_change
  freshness_sla: 4h
  availability_target: 99.9%

change_management:
  breaking_change_requires_approval: true
  consumer_impact_review: true
  migration_required: true

failure_policy:
  critical_violation: block
  recovery: last_verified_version

这里的4h和99.9%仅为示例目标，不能理解为工业企业或SEO/GEO行业统一采用的官方SLA。

而且，对于canonical_consistency和evidence_verified等规则，还必须提供实际执行实现。

不能只因为YAML中写了这两项，便认为系统已经具备验证能力。

这也是Data Contract制度建设中常见的形式主义风险：

契约写得很完整，但没有真正的Enforcement Point。

九、Data Contract必须区分三类规则

为了使治理体系可以执行，本系列建议将契约规则分成三类。

规则类别	典型内容	主要执行位置
Structural Rule	字段存在、数据类型、JSON格式	Schema Validator
Semantic & Quality Rule	单位、Authority、Context、业务定义、一致性	Data Quality Engine / Owner Review
Operational Rule	SLA、版本通知、消费者迁移、回滚	CI/CD / Change Workflow / Monitoring

这三类规则不能简单使用同一把尺子衡量。

Schema Validator可以自动发现缺少evidence_id。

但是否拥有充分的工程证据，可能需要进一步查询Evidence Registry。

它可以发现rated_power_kw被修改为字符串。

但判断字段改名对所有消费者的影响，还需要Consumer Contract Testing。

对于跨国销售、产品合规等高风险语义变更，甚至需要具有业务Authority的人员审批。

因此：

Contract Enforcement应当采用多层验证，而不是把所有责任交给一个Schema校验工具。

十、Breaking Change：什么样的数据变化会破坏下游？

Data Contract真正产生价值的地方，往往是在系统变更时。

企业过去容易把变更分成大改动和小改动，但这种区分过于主观。

对于Consumer来说，一次看起来很小的字段修改也可能造成业务中断。

本系列建议用更明确的判断标准：

如果一次变更使任何已登记、受支持的Consumer无法继续满足其约定的功能、数据含义或性能要求，就应被视为潜在Breaking Change。

例如：

变更	是否可能破坏兼容性	原因
删除必填字段	是	Consumer失去依赖数据
rated_power_kw改为power	是	字段名称变化
Number改为String	是	类型依赖被破坏
kW改为W但字段名称不变	是	语义及单位变化
Optional改为Required	是	旧数据可能不满足新规则
新增Optional字段	视情况而定	严格消费者可能拒绝未知字段
增加枚举值	视情况而定	Consumer可能没有新值处理逻辑
修改字段描述但含义不变	通常影响较低	仍需确认语义没有变化
调整数据刷新时间	视情况而定	可能违反下游SLA
修改Product ID生成规则	高风险	实体关联可能断裂

其中，“新增Optional字段通常是安全的”这一说法也必须限定条件。

例如，前文JSON Schema使用了additionalProperties: false。

这意味着旧版严格Validator可能拒绝新的未知字段。

因此，即使Producer认为只是添加一个可选属性，下游仍可能发生兼容性故障。

Breaking Change应当按照真实消费者和实际Schema行为判断，而不能只凭字段变更名称决定。

十一、Backward、Forward、Full Compatibility究竟有什么区别？

兼容性是一个经常被混淆的概念。

Confluent Schema Registry的官方文档清晰区分了Backward Compatibility、Forward Compatibility、Full Compatibility以及Transitive Compatibility等模式。

官方参考：Confluent — Schema Evolution and Compatibility

其基本含义可以通过生产者和消费者的版本关系理解。

Backward Compatibility

新的Consumer能够处理旧版本Producer产生的数据。

Old Data
    ↓
New Consumer

这有利于消费者先升级。

Forward Compatibility

旧的Consumer仍能处理新版本Producer产生的数据。

New Data
    ↓
Old Consumer

这有利于生产者先升级。

Full Compatibility

上述两个方向均满足约定的兼容条件。

Old Data → New Consumer
New Data → Old Consumer

但这里还需要明确：Confluent不同Schema格式，例如Avro、Protobuf和JSON Schema，具有不同的演进规则。

不能把Avro中的兼容行为直接推广到所有JSON接口。

尤其对于企业自己设计的HTTP JSON接口，兼容性检查需要结合实际验证器、接口协议和消费者行为实现。

十二、为什么还需要Transitive Compatibility？

假设某项数据契约已经演进了三个版本：

Contract v1
    ↓
Contract v2
    ↓
Contract v3

如果只检查v3能否兼容v2，不代表它必然也能够兼容v1。

但现实中，企业可能仍然有某个经销商系统使用v1接口。

因此，部分场景需要：Transitive Compatibility。

它要求新版本按照指定的兼容性方向，与所有需要支持的历史版本进行检查。

Confluent明确区分非传递与传递兼容性，并指出其Schema Registry默认的BACKWARD并不等同于BACKWARD_TRANSITIVE。

这对SEO/GEO企业尤其重要。

因为官网、经销商、销售系统、PDF生成器和AI知识库可能并不会在同一天完成升级。

所以企业不能只问“最新系统能不能运行？”

还应该问：

“我们承诺支持的旧系统，是否仍然能够安全消费新数据？”

十三、Contract Version不应该与Data Version混为一谈

这是实施中另一种常见错误。

假设工程数据版本：Engineering Specification V4.2。

而Data Contract版本：Product Contract 1.3.0。

这两个版本记录不同的变化。

工程数据版本说明：事实内容发生了什么变化。

Data Contract版本说明：数据交付方式、结构、语义或约定发生了什么变化。

例如额定功率从80 kW正式变为82 kW。

如果接口结构、字段定义与使用规则没有变化，可能只需要更新数据版本。

但如果rated_power_kw被重新命名、字段类型发生变化、单位被改变、Consumer必须采用新的读取方式，那么Contract Version也需要升级。

因此：

Data Version
≠
Contract Version
≠
Schema Version

此外，业务上还有一个经常被忽视的版本：Transformation Version。

例如功率的单位换算规则发生变化，即使输入Schema没有变化，也可能导致下游输出结果不同。

这些版本应该分别记录，并通过Provenance建立关联。

十四、如何建立Breaking Change审批制度？

契约变更不应该由开发人员直接修改字段后上线。

尤其是已经被多个系统消费的生产数据。

建议采用：Contract Change Request（CCR）。

一份变更申请至少包含：

change_id:
CCR-2026-0042

contract_id:
DC-PRODUCT-FACT-001

current_version:
1.0.0

proposed_version:
2.0.0

change:
Rename rated_power_kw
to rated_power

reason:
Interface redesign

affected_consumers:
PIM
WordPress
PDF Generator
RAG

breaking_risk:
HIGH

producer_owner:
Engineering

consumer_approval:
REQUIRED

migration_plan:
REQUIRED

rollback_plan:
REQUIRED

示例中的ID与日期仅用于说明。

真正的变更流程应该是：

Change Request
       ↓
Contract Diff
       ↓
Breaking Change Analysis
       ↓
Consumer Impact Review
       ↓
Owner Approval
       ↓
Contract Testing
       ↓
Migration / Deployment
       ↓
Production Verification

其中：Producer负责提出和实现变更。Consumer负责确认自身能否继续使用。Data Owner负责裁决业务语义及风险。Data Steward负责维护契约登记、测试状态和变更证据。

不能简单认为通过一次开发Pull Request审核，就已经完成所有业务责任审批。

十五、一个可执行的版本迁移策略：Expand → Migrate → Contract

对于可能破坏兼容性的变更，直接删除旧字段通常不是最优做法。

可以采用软件系统中成熟的渐进式迁移思想：

Expand → Migrate → Contract。

Expand：先扩展，而不是先删除

Producer暂时同时支持：

{
  "rated_power_kw": 82,
  "rated_power": 82
}

但这只是说明迁移策略，不能直接认为两种字段语义完全相同。

新字段应具有明确单位和定义。

如果新接口准备改变单位或业务含义，必须显式声明新的字段或数据对象。

Migrate：逐个迁移消费者

PIM更新映射。

WordPress更新模板字段。

PDF生成器更新读取逻辑。

RAG同步程序采用新字段。

每个Consumer完成验证并确认其使用版本。

Contract：在完成迁移后移除旧字段

当所有仍受支持的Consumer完成迁移，旧字段才能按照退役计划移除。

如果企业无法控制全部Consumer，可以继续提供明确期限内的旧版接口，或者为旧版客户端维持Adapter。

这比要求所有系统在同一时刻切换更稳妥。

但也必须注意：长期无限期维护旧版本会带来成本和安全风险。

因此迁移计划应包含明确的Deprecation Notice、停止新增依赖的日期、迁移窗口、最终停用日期、例外审批。

这使Data Contract从一个静态文件变成有生命周期的制度。

十六、CI/CD：如何在代码合并之前自动验证Data Contract？

真正的工程落地，必须能够把契约检查放入CI/CD。

可以先建立一个简单的目录：

repository/
├── contracts/
│   └── product-fact.v1.schema.json
├── fixtures/
│   └── product.valid.json
├── scripts/
│   └── check_contract.py
└── .github/
    └── workflows/
        └── data-contract.yml

其中contracts保存Schema，fixtures保存代表性测试数据，scripts负责执行验证，GitHub Actions在Pull Request阶段执行检查。

下面给出一个最小的Python验证程序。

import json
from pathlib import Path

from jsonschema import Draft202012Validator, FormatChecker

schema = json.loads(
    Path("contracts/product-fact.v1.schema.json")
    .read_text(encoding="utf-8")
)

sample = json.loads(
    Path("fixtures/product.valid.json")
    .read_text(encoding="utf-8")
)

Draft202012Validator.check_schema(schema)

validator = Draft202012Validator(
    schema,
    format_checker=FormatChecker()
)

errors = list(validator.iter_errors(sample))

if errors:
    for error in errors:
        print(f"Contract violation: {error.message}")
    raise SystemExit(1)

invalid_sample = dict(sample)
invalid_sample.pop("evidence_id")

if validator.is_valid(invalid_sample):
    raise SystemExit(
        "Negative test failed: missing evidence_id was accepted"
    )

print("Schema validation passed")

这个程序验证三件事。

第一，Schema本身符合所选JSON Schema草案要求。

第二，合法的示例数据能够通过。

第三，当必填的evidence_id缺失时，验证器必须拒绝。

对应的GitHub Actions可以写成：

name: Data Contract Validation

on:
  pull_request:
    paths:
      - "contracts/**"
      - "fixtures/**"
      - "scripts/check_contract.py"

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install validator
        run: python -m pip install "jsonschema>=4,<5"

      - name: Validate contract fixtures
        run: python scripts/check_contract.py

这是一个能够作为初始工程模板的最小例子。

但必须明确：

它目前只验证Schema及测试样本，不等于完整的Data Contract Enforcement。

它还不能自动发现所有Breaking Change，不能核实工程事实是否准确，不能确保所有Consumer都已完成迁移，不能验证企业定义的全部SLA，也不能直接证明生产环境中的所有真实数据都符合契约。

所以，企业应该把它看作第一道CI检查，而不是治理完成的证明。

十七、完整的CI/CD Contract Gate还需要什么？

建议在最小Schema验证基础上，逐步增加四种测试。

Contract Schema Test

验证结构、字段和数据类型。

Contract Compatibility Test

比较当前版本与上一受支持版本，检查是否存在潜在Breaking Change。

Consumer Contract Test

使用真实消费者声明的字段依赖、样本、Adapter或契约测试，确认下游仍然能够正常运行。

Semantic & Quality Gate

检查单位、业务定义、Authoritative Source、关键质量规则、审批状态和使用资格。

最终形成：

Pull Request
      ↓
Schema Validation
      ↓
Compatibility Diff
      ↓
Consumer Regression Test
      ↓
Semantic & Quality Review
      ↓
Required Approval
      ↓
Merge / Deploy

对于高度自动化且风险较低的变更，可以将大量检查交给CI。

对于关键工程参数、价格、认证和合规数据的语义变化，应保留业务审批。

不能因为代码检查显示绿色，就认为业务事实的含义已经获得授权。

十八、Data Contract如何进入WordPress与SEO内容生产？

对于使用WordPress管理外贸独立站的企业，这个问题具有很强的实践价值。

传统流程中，产品数据经常通过Excel导入、ACF字段编辑、REST API同步、插件生成Schema、人工复制技术参数。

这些方式可能分别正常工作，但缺少共同的数据契约。

例如，PIM输出：

rated_power_kw

ACF字段使用：

product_power

Rank Math的结构化数据映射又读取第三个字段。

这意味着：

三个系统可能正在使用三种不同的字段命名和数据解释方式。

本系列建议，将数据契约放在PIM与CMS的数据交换边界。

Approved PLM Data
       ↓
Canonical Product Service
       ↓
Data Contract Validation
       ↓
WordPress REST API
       ↓
ACF / Product Template
       ↓
HTML + Structured Data

具体可以采用：Canonical Field Mapping。

例如：

权威数据属性	数据契约字段	WordPress字段	输出用途
Rated Power	rated_power_kw	product_rated_power_kw	技术规格
Product Model	product_id	product_model	产品身份
Configuration	configuration_id	product_configuration	配置上下文
Evidence	evidence_id	内部来源字段	审计追溯
Specification Version	spec_version	内部版本字段	更新判断

这里的字段名只是演示性内部映射，真正实施时应根据现有PIM、ACF和接口定义确定。

核心原则是：

映射关系应当受版本管理，而不是分散在不同插件和代码片段中。

当Contract Version发生变化时，CMS适配器必须经过对应的兼容性测试。

这可以减少因为上游字段改名导致的产品页面参数丢失。

十九、SEO Schema与Data Schema不是同一个东西

这里必须澄清三个容易混淆的概念。

Data Schema用于规定数据结构、类型及约束。

Schema.org Vocabulary用于描述网页中的实体、类型和属性等语义信息。

Google Structured Data Requirements则规定在Google Search特定搜索展示功能中，对结构化数据的支持和质量要求。

它们不能被简单等同。

例如，企业可以使用JSON Schema验证产品数据接口中的rated_power_kw。

但这不意味着Google Search直接读取这个内部字段。

WordPress仍然需要按照实际支持的Schema.org类型和属性生成结构化数据。

Google Search Central也明确要求结构化数据应与页面实际内容保持一致、保持相关性，并避免误导。

官方参考：Google — General Structured Data Guidelines

因此，一个成熟的发布流程应至少完成三种检查：

Internal Data Contract Validation。

CMS Content Consistency Validation。

Applicable Structured Data Validation。

这三道检查共同提高数据发布的可靠性，但并不保证搜索排名或Rich Result展示。

二十、GA4与数字营销数据同样需要Contract

Data Contract不仅适用于产品数据。

数字营销领域甚至更容易出现没有人意识到的Breaking Change。

例如，一个网站原来将有效询盘事件命名为generate_lead。

后来团队把自定义埋点改成form_success。

前端仍然能够触发事件。GA4也可能正常接收符合要求的事件。

但原有报表、关键事件配置、营销自动化和Looker Studio指标可能仍然依赖旧名称。

结果：表单提交正常，网站运行正常，但管理层发现“询盘转化量突然下降”。

这不一定是真实业务下滑，也可能是：

Measurement Contract Breaking Change。

因此，营销事件同样需要建立数据契约。

例如：

event_name:
generate_lead

business_meaning:
Qualified form submission

trigger_condition:
Validated successful submission

producer:
Website Event Layer

consumers:
GA4
Looker Studio
CRM Attribution

required_parameters:
form_id
lead_type

change_policy:
Consumer Review Required

这里属于企业自定义的事件契约示例，不是对GA4所有官方事件参数的完整描述。

真正实施时，需要区分Google Analytics的官方事件规范、网站自己的业务定义与下游报表依赖。

尤其不能把“事件触发了”直接等同于“真实产生了一条有效销售线索”。

二十一、AI知识库也应该成为Data Consumer

对于RAG系统，Data Contract具有另一层重要意义。

知识库的上游来源可能是PLM、PIM、CMS、产品PDF、内部知识管理系统。

如果RAG Ingestion只关心文件能不能读取、文本能不能切分、Embedding能不能生成，那么它仍然可能把无权发布、过期或缺乏证据的数据导入正式知识层。

因此，RAG数据消费者应该明确声明：

required_metadata:
  - source_id
  - document_version
  - evidence_id
  - knowledge_status
  - effective_from

allowed_status:
  - VERIFIED
  - AUTHORITATIVE

on_contract_failure:
  - quarantine
  - create_issue
  - exclude_from_index

上述内容是本系列自定义的RAG Contract Policy示例。

它表达的核心思想是：

RAG不应该仅仅要求上游提供可读取文本，还应要求上游提供必要的来源、版本和治理元数据。

需要注意，即使元数据完整，也仍然需要第七篇的事实质量验证。

Data Contract只是使这些要求可以提前声明并被系统检查。

二十二、Contract Violation之后应该发生什么？

建立契约并不意味着所有变更都会被自动禁止。

企业仍然需要正常升级系统。

真正重要的是：当Producer不能满足既定Contract时，系统是否知道应该采取什么动作。

本系列建议区分四种处理。

BLOCK：关键结构、语义或业务规则失败，阻止进入对应生产环境。

QUARANTINE：数据可能有价值，但暂时缺少证据、版本或审批，进入隔离区。

DEFER：变更已经提出，但尚未完成消费者迁移或依赖确认，延后部署。

ALLOW WITH APPROVAL：经过明确的风险评估、审批和补偿措施后，允许受控例外。

注意：ALLOW WITH APPROVAL不能成为绕过合规、安全和关键事实校验的通用后门。

每个例外必须具有具体原因、批准责任人、适用范围、有效期限、必要的回滚方案、审计记录。

当契约违约已经影响生产环境时，应建立Data Contract Incident，并与第七篇的Data Quality Incident关联。

因为一个事件可能同时包含上游不兼容变更、下游数据质量异常、内容发布错误。

这三者需要协同处理，但不一定具有同一个根因。

二十三、建立Data Contract Registry

当企业逐渐拥有多个接口时，不能将契约文件随意分散存放。

建议建立统一的：Data Contract Registry。

至少记录：

字段	用途
contract_id	契约唯一ID
contract_version	契约版本
producer_id	数据生产者
consumer_ids	已登记消费者
schema_ref	Schema位置
semantic_definition_ref	业务定义
quality_rule_ref	数据质量规则
source_authority_ref	权威来源规则
sla_ref	服务等级约定
compatibility_mode	兼容性策略
status	Draft / Active / Deprecated / Retired
approved_by	审批责任人
last_validated_at	最近验证时间

其中：Contract Registry并不是另一个孤立的管理系统。

它应该与前面建立的Source Registry、Data Ownership Registry、Claim Registry、Data Quality Rule Registry、Distribution Registry，通过稳定ID建立关联。

这才能形成完整的治理链路。

例如一个WordPress产品页面读取了错误数据，企业可以进一步追溯：

它消费的是哪个Contract Version？

哪个Producer交付的数据？

上游依据哪份Source？

质量验证使用了哪版规则？

是否存在未完成的Breaking Change？

这就是Data Contract在整体数据治理体系中的真正位置。

二十四、Data Contract应该怎样度量？

企业不能仅仅统计“我们建立了多少份数据契约”。

因为Contract数量增加，并不必然说明质量提高。

更值得持续衡量的指标包括：

Contract Coverage Rate

已建立并生效契约的关键数据接口数量，占关键接口总数的比例。

Producer Conformance Rate

在规定观察窗口内，符合契约要求的数据交付次数占比。

Consumer Compatibility Pass Rate

受支持消费者在契约版本变更测试中的通过比例。

Unauthorized Breaking Change Count

未经要求的审批与迁移流程，直接进入生产环境的不兼容变更次数。

Contract Violation Detection Time

从首次发生违约到被检测发现的时间。

Contract Incident Resolution Time

契约异常从登记到修复、复测和必要的下游验证完成所需时间。

这里必须保持指标定义的精确性。

例如Producer Conformance Rate需要明确：按请求计算、按批次计算、按记录计算，还是按时间窗口计算？

这些方法会产生不同的结果。

同样，Contract Coverage Rate达到100%，也不意味着企业全部数据都准确。

它只能说明既定范围内的关键接口已经建立契约。

因此，Data Contract指标应与Data Quality、Provenance和Publication Quality共同观察。

二十五、中小型B2B企业如何用30天建立第一版Data Contract？

对于已经使用WordPress、ACF、PIM、GA4和基础自动发布工具的企业，不建议一开始就建设复杂的Enterprise Contract Platform。

可以从一个关键流程入手。

第1周：识别生产者和消费者

选择产品数据同步场景。

梳理：工程规范由谁批准？PIM读取什么？WordPress使用哪些字段？PDF生成器依赖哪些属性？AI知识库使用哪些元数据？

形成Producer–Consumer Dependency Map。

第2周：建立结构与语义契约

选择10—20个关键字段。

为它们定义：字段名称、类型、单位、业务含义、Context、必填条件、Source of Truth、版本要求。

用JSON Schema或等效方式完成基本结构约束。

第3周：建立CI/CD Contract Testing

至少完成：

Schema验证。

有效样本验证。

无效样本拒绝测试。

关键字段兼容性检查。

Consumer测试样本回归。

需要人工审批的语义变更识别。

将其中可以自动化的部分接入现有代码仓库。

第4周：建立变更和异常闭环

正式定义Breaking Change判定条件、版本策略、通知责任、消费者迁移窗口、回滚方案、异常工单和审批流程。

最终形成的交付不应该只是几份YAML或JSON文件。

而应该是：

Contract Registry + Executable Validation + Consumer Testing + Change Control + Incident Resolution。

这才是第一版真正可运行的数据契约体系。

二十六、SEO / GEO Data Contract的MUST、SHOULD、MAY规范

以下要求属于本系列为企业SEO/GEO数据实践设计的实施规范，并不代表Bitol、W3C、Google或其他组织联合发布了SEO/GEO数据契约强制标准。

MUST｜必须

MUST-01：关键跨系统数据接口必须具有明确的Producer和Consumer责任边界。

MUST-02：关键数据契约必须明确字段结构、数据类型及必要业务语义。

MUST-03：契约必须拥有稳定ID与版本标识。

MUST-04：Critical Data Element不得在未经授权的情况下改变其业务含义、单位或Authority。

MUST-05：已登记生产消费者之间的潜在Breaking Change必须经过影响分析。

MUST-06：关键接口发布前必须执行适用的结构与兼容性验证。

MUST-07：影响关键消费者的Breaking Change必须具备明确迁移或替代方案。

MUST-08：关键契约变更必须保留审批、执行和验证记录。

MUST-09：Critical Contract Violation必须能够阻止数据进入未经批准的生产用途。

MUST-10：Schema Validation Pass不得直接等同于Data Quality Pass、Semantic Approval或Publication Authorization。

SHOULD｜建议

企业应建立统一的Data Contract Registry。

应记录实际Consumer依赖关系，而不仅仅登记系统名称。

应采用受控的Contract Versioning和Deprecation Policy。

应将结构验证、消费者测试和质量门禁逐步接入CI/CD。

应为关键契约建立可观测的SLA、失败告警和变更回滚机制。

应将契约违约事件与Data Quality Incident关联，形成根因和影响追踪。

MAY｜可选

成熟企业可以进一步采用：

Open Data Contract Standard。

Schema Registry。

OpenAPI。

dbt Model Contracts。

Consumer-driven Contract Testing。

Automated Schema Diff。

Policy as Code。

Event-driven Validation。

Contract Observability。

Automated Consumer Migration。

这些技术并不是必须同时部署。

关键是选择符合企业系统规模、风险等级和维护能力的组合。

二十七、Data Contract Checklist：发布前应该检查什么？

每次重要数据结构或接口变更之前，都应该能够回答：

• 谁是Producer，谁是已登记Consumer？
• 契约使用哪个版本？
• Schema是否完整、可验证？
• 字段定义、单位和Context是否明确？
• 是否存在新旧Schema结构差异？
• 是否发生潜在Semantic Breaking Change？
• 新版本能否满足已承诺的兼容性要求？
• 是否需要消费者先升级？
• 是否存在仍依赖旧版本的系统？
• 是否完成代表性Consumer Regression Test？
• 是否通过第七篇的Data Quality Gate？
• 是否涉及需要Owner审批的业务事实？
• 变更是否具有迁移、回滚和异常处理方案？
• 合并代码以后，是否还有生产环境验证？
• 数据最终进入CMS和AI知识库时，是否保留来源与版本关系？

如果这些问题无法回答，企业实际上仍然依赖：Deploy First, Fix Later。

也就是：先上线，再排查问题。

Data Contract所要改变的，正是这种工作方式。

二十八、Data Contract真正要改变的，是数据生产和使用之间的协作关系

从前七篇走到这里，我们已经可以看到数据治理体系的演进。

第一篇让企业认识数据的价值。

第二篇建立数据生命周期。

第三篇确定Source of Truth。

第四篇明确Data Ownership。

第五篇控制Source Admission。

第六篇建立Provenance。

第七篇形成Data Quality Gate。

第八篇则把这些要求向数据生产和系统交换边界前移。

整个过程可以表示为：

Data Producer
      ↓
Data Contract
      ↓
Schema & Semantic Validation
      ↓
Compatibility Testing
      ↓
Quality Gate
      ↓
Approved Data Interface
      ↓
PIM / CMS / Analytics / RAG
      ↓
Publication & Monitoring

这条链路最重要的变化，不是又增加了一套技术文件。

而是：

消费者不必等到系统出错，才知道上游破坏了自己依赖的数据约定。

Producer也不再需要依靠猜测判断自己的变更是否安全。

双方能够通过明确的契约、版本、测试和审批机制，进行可预测的数据协作。

写在最后：数据不应该进入系统以后，才第一次知道自己不合格

过去，企业经常采用一种被动的数据工作方式。

数据先进入系统，然后清洗，然后发现缺失，然后修改，然后同步，然后发现另一个系统无法使用，然后重新调整。

这种过程并非完全可以避免。

但当大量错误都来自未声明的字段、规则和依赖关系时，企业就不应该始终依靠事后修复。

AI时代让这个问题变得更加重要。

因为一项上游数据变化，可能同时影响产品页面、技术PDF、Schema、报价、分析报表、知识库、AI Agent。

如果没有Data Contract，这些系统只能被动承受上游变化。

而建立Data Contract以后，企业至少可以在正式生产之前明确：

哪些内容不能随意改变。

哪些改变必须升级版本。

哪些消费者需要提前通知。

哪些质量规则必须通过。

哪些变更必须阻止。

哪些异常需要人工裁决。

所以，第八篇的核心结论不是“所有数据都应该使用某个特定Schema标准”。

而是：

真正成熟的数据治理，应当使关键数据在被生产、交换和消费之前，就拥有明确的结构、语义、质量与变更约定，并通过可执行检查保证这些约定得到遵守。

Data Quality解决：

数据是否合格。

Data Contract进一步解决：

谁有义务交付合格数据，以及怎样在改变交付方式时保护下游消费者。

当二者结合起来，数据治理才能从被动纠错进一步走向主动预防。

下一篇

《SEO / GEO 数据治理与规范标准细则（九）：Metadata Governance——为什么企业不能只有数据，却没有描述数据的标准？》

第八篇已经把Schema、字段语义、质量规则和版本兼容性纳入数据交换约定。

但接下来，企业还需要进一步回答：

这些字段、规则、Owner、来源、质量状态和消费关系，究竟应该怎样被统一描述、登记、发现和维护？

如果不同系统拥有不同的Metadata定义，企业即使建立了Data Contract，也很容易出现：字段定义不一致、术语冲突、Owner失效、版本不清、Lineage断裂、AI知识检索缺少必要上下文。

第九篇将从Data Contract继续推进到：

Metadata Standard、Business Glossary、Technical Metadata、Operational Metadata、Metadata Registry、Metadata Quality及Metadata Lifecycle。

最终建立：

SEO / GEO Metadata Governance Standard。

参考依据与标准边界

1. Open Data Contract Standard（ODCS）— Bitol

提供跨平台描述数据契约的开放规范，包括基本信息、Schema、Data Quality、支持与沟通、团队角色、SLA、权威定义及其他属性。

官方地址：https://bitol-io.github.io/open-data-contract-standard/latest/

官方仓库：https://github.com/bitol-io/open-data-contract-standard

2. JSON Schema Draft 2020-12

为JSON数据的结构和约束提供规范，包括Required、Properties、Type及其他验证关键词。

官方地址：https://json-schema.org/draft/2020-12

3. OpenAPI Specification 3.1

提供HTTP API的标准描述能力，支持使用与JSON Schema Draft 2020-12相关的Schema表达数据模型。

官方地址：https://spec.openapis.org/oas/v3.1.1.html

4. dbt — Model Contracts

介绍如何通过Model Contract对模型输出列、数据类型及平台支持的约束建立保证，并在构建过程中执行验证。

官方地址：https://docs.getdbt.com/docs/mesh/govern/model-contracts

5. Confluent — Schema Evolution and Compatibility

详细解释Backward、Forward、Full与Transitive等Schema兼容性模式，并说明不同Schema格式的演进约束。

官方地址：https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html

6. Google Search Central — General Structured Data Guidelines

说明Google Search结构化数据的质量与技术要求，强调内容准确、相关、真实反映页面信息，并不保证通过技术检查后一定获得Rich Result展示。

官方地址：https://developers.google.com/search/docs/appearance/structured-data/sd-policies

本系列自定义实施规范说明

本文提出的 SEO / GEO Data Contract Record、Consumer Dependency Map、Semantic Contract Gate、Contract Change Request、Contract Registry、Contract Incident、质量与兼容性分层验证、MUST / SHOULD / MAY规则及30天实施路径，属于本系列结合SEO、GEO、PIM、WordPress、GA4、RAG和数字营销应用设计的工程化实施框架。

文中的YAML契约示例不是完整ODCS规范文件；Python和GitHub Actions示例属于最小Schema验证实现，不涵盖全部语义、兼容性和生产运行保证。

Data Contract有助于提升数据交换的稳定性、可维护性和治理能力，但不直接保证Google排名、AI引用或营销转化结果。