OpenMetadata ODCS 数据契约导入测试指南：v3.1.0 示例集与导入流程全解

OpenMetadata ODCS 数据契约导入测试指南：v3.1.0 示例集与导入流程全解

【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata

ODCS（Open Data Contract Standard，开放数据契约标准）是跨平台描述数据契约（Data Contract）的行业规范，OpenMetadata 在后端通过 ODCSConverter.java 实现与 ODCS v3.1.0 格式的双向转换，并在前端提供「Import from ODCS」导入能力。本文以仓库中openmetadata-ui/src/main/resources/ui/playwright/test-data/odcs-examples/目录下的官方测试样例为骨架，系统讲解 ODCS 契约文件的字段语义、合法/非法样例设计、导入的三种模式（新建 / 合并 / 替换）、多对象契约处理以及质量规则与 SLA 的映射原理，帮助开发者快速上手 ODCS 导入功能的手工验证与 Playwright 自动化测试。

ODCS 测试示例目录总览

odcs-examples目录存放了用于手工测试 ODCS 导入功能的示例文件，全部位于 test-data/odcs-examples/ 下，分为三类：合法示例（Valid Examples）、与 sample_data 兼容的示例（Sample Data Compatible Examples）与非法示例（Invalid Examples）。它们同时被 Playwright 端到端测试 ODCSImportExport.spec.ts 直接引用（测试注释明确写道"Tests using actual test-data files from test-data/odcs-examples/"），因此既是手工验证的素材，也是自动化测试的黄金数据集。

合法示例（Valid Examples）

此外目录中还提供了 README 表格之外但同样被测试引用的样例：valid-quality-rules-between.yaml（mustBeBetween/mustNotBeBetween断言）、valid-with-team.yaml、valid-full-no-schema.yaml（无 schema 的完整契约）以及 invalid-schema-fields.yaml（字段与目标表不匹配）。

与 sample_data 兼容的示例

以下文件与 OpenMetadata 内置 sample_data 服务中的真实表结构一一对应，用于在 sample_data 服务上进行端到端验证：

以 sample-data-dim-address.yaml 为例，它的schema.properties完整列出了address_id、shop_id、first_name、last_name、address1、address2、company、city、region、zip、country、phone共 12 个字段，并标注了复合主键（address_id+shop_id，通过primaryKeyPosition: 1/2表示次序），因此导入时可以与真实表的列做逐字段校验。

非法示例（Invalid Examples）

这些非法样例被 ODCSImportExport.spec.ts 中的常量（如ODCS_INVALID_MISSING_APIVERSION_YAML、ODCS_INVALID_MALFORMED_YAML等，定义于 playwright/constant/dataContracts.ts）逐一消费，用于断言错误提示与导入按钮禁用态。

ODCS v3.1.0 核心文件结构剖析

在深入测试场景前，先理解一个合法 ODCS 契约文件的最小结构。以下是最小合法契约 valid-basic.yaml 的完整内容（Apache 2.0 许可证头已省略）：

apiVersion: v3.1.0 kind: DataContract id: basic-contract name: Basic ODCS Contract version: '1.0.0' status: active

五个字段缺一不可：apiVersion声明标准版本（当前仓库后端固定导出为V_3_1_0，见ODCSConverter.toODCS()中odcs.setApiVersion(ODCSDataContract.OdcsApiVersion.V_3_1_0)）；kind固定为DataContract（ODCSDataContract.OdcsKind.DATA_CONTRACT）；id为契约唯一标识（导入时被忽略，由 OpenMetadata 自行生成 UUID）；name映射为 OpenMetadata 契约的name；version为语义化版本号，映射为contractVersion；status取值active或draft。

完整契约：description / slaProperties / roles

valid-full.yaml 展示了包含全部核心 section 的写法：

apiVersion: v3.1.0 kind: DataContract id: full-contract name: Complete ODCS Contract version: '2.0.0' status: active description: purpose: Comprehensive data contract for customer analytics. limitations: Historical data only, no PII exposed. usage: For internal analytics dashboards and ML models. slaProperties: - property: freshness value: '12' unit: hour - property: latency value: '2' unit: hour - property: retention value: '365' unit: day roles: - name: data_admin description: Full access to all data access: readWrite - name: analyst description: Read-only access for analysis access: read

其中description的三个子字段（purpose、limitations、usage）语义分别对应契约用途、限制与使用场景；slaProperties是一个属性数组，property取值如freshness（新鲜度）、latency（延迟）、retention（保留期），配合value+unit表达量化指标；roles定义数据访问角色（如readWrite/read）。在 OpenMetadata 中，description.purpose映射为契约的description，slaProperties映射为sla，roles直接映射为roles（详见下文「OpenMetadata 字段映射」小节）。

v3.1.0 新增特性：时间类型与 SLA 时区

ODCS v3.1.0 引入了两类关键增强，valid-with-timestamps.yaml 专门用于覆盖：

• logicalType: timestamp与logicalType: time：schema 字段可声明时间戳与时间逻辑类型，并支持时区选项；
• SLA 时区字段：slaProperties条目可携带timezone，例如：

slaProperties: - property: freshness value: '6' unit: hour timezone: GMT+00:00 UTC - property: latency value: '15' unit: minute - property: availability value: '99.9' unit: percent timezone: GMT-05:00 America/New_York

注意同一契约中不同 SLA 属性可指定不同时区（如 UTC 与 America/New_York），便于表达跨地域的数据承诺。此外 v3.1.0 还包括质量指标库（rowCount、nullValues、invalidValues、duplicateValues、missingValues）与质量调度（scheduler+schedule字段），在下一节展开。

质量规则（Quality）详解

valid-quality-rules.yaml 是质量规则最完整的示例，包含库内置指标、自定义 SQL 规则与定时调度三类：

schema: - name: products logicalType: object properties: - name: sku logicalType: string primaryKey: true - name: product_name logicalType: string required: true - name: price logicalType: decimal logicalTypeOptions: precision: 10 scale: 2 - name: stock_quantity logicalType: integer - name: last_updated logicalType: timestamp quality: # 库内置指标（built-in library metrics） - type: library rule: rowCount mustBeGreaterThan: 1000 description: Product catalog must have at least 1000 items - type: library rule: nullValues column: sku mustBe: 0 description: SKU cannot be null - type: library rule: duplicateValues column: sku mustBe: 0 description: SKU must be unique - type: library rule: invalidValues column: category mustBeLessThan: 5 - type: library rule: missingValues column: price mustBeLessThanOrEqualTo: 10 description: Allow up to 10 missing prices # 自定义 SQL 规则 - type: custom rule: 'price > 0' column: price description: Price must be positive - type: custom rule: 'LENGTH(sku) BETWEEN 8 AND 12' column: sku # 定时质量检查 - type: library rule: nullValues column: last_updated scheduler: cron schedule: '0 6 * * *' description: Daily check for update timestamps

要点归纳：

• type: library使用内置指标库，rule支持rowCount、nullValues、invalidValues、duplicateValues、missingValues，并可与column组合限定作用列；
• 断言关键字：mustBe、mustBeGreaterThan、mustBeLessThan、mustBeLessThanOrEqualTo。目录中另有 valid-quality-rules-between.yaml 补充mustBeBetween与mustNotBeBetween区间断言，以及同一指标多断言叠加（如uniqueValues同时满足mustBeGreaterThan: 0与mustBeLessThan: 1000000）；
• type: custom直接书写 SQL 表达式作为自定义校验规则，如price > 0、LENGTH(sku) BETWEEN 8 AND 12；
• 调度：scheduler: cron+schedule: '0 6 * * *'声明每日 6 点执行；
• schema 字段的logicalTypeOptions可携带precision/scale等类型参数，required/primaryKey表达约束。

在 OpenMetadata 后端，质量规则通过 ODCSConverter 转换为测试用例（Test Case），即 README 映射表中的quality → Mapped to test cases。导入后这些规则会落为可执行的数据质量测试，而非仅停留在契约文档层面。

多对象（Multi-Object）契约

ODCS 契约的schema是一个数组，可以同时描述多个表对象。valid-multi-object.yaml 定义了customers、orders、products三个对象；而 sample-data-multi-object.yaml 则贴合 sample_data 定义dim_address、dim_customer、dim_location三个对象，每个对象都声明logicalType: object、physicalType: table，并各自携带独立的properties（字段集合）与description。

导入多对象契约时，UI 会提示"This contract contains multiple schema objects"，并展示对象选择下拉框；Import 按钮在用户选定对象前保持禁用，选定后校验与导入都基于所选对象进行，最终契约只保留选中对象的 schema——这保证了「一个契约对应一张表」的语义不会因多对象文件而破坏。

OpenMetadata 字段映射表

导入/导出时，ODCS 字段与 OpenMetadata DataContract 字段的对应关系如下（源自 README.md 并可由 ODCSConverter.java 的双向转换逻辑佐证）：

手工测试场景（7 大场景逐步验证）

以下场景按 README 提供的手工测试脚本整理，覆盖从无契约新建到错误处理的完整闭环。

场景 1：新建契约导入（无既有契约）

1. 进入一张尚无数据契约的表；
2. 点击"Add Contract" > "Import from ODCS"；
3. 上传任意合法文件（如valid-basic.yaml）；
4. 校验契约预览信息正确；
5. 点击Import；
6. 校验契约以正确数据创建。

场景 2：与既有契约合并（Merge）

1. 进入一张已有数据契约的表；
2. 点击Manage > "Import ODCS"；
3. 上传合法文件；
4. 校验出现"Existing contract detected"警告；
5. 选择"Merge with existing"选项；
6. 校验合并说明描述了将要发生的行为；
7. 点击Import；
8. 校验既有 ID 被保留、新字段被合并。

合并语义在测试 ODCSImportExport.spec.ts 中被严格断言：合并后原契约名称被保留（"original contract name is preserved (merge behavior)"），来自完整契约的 SLA 与 roles 被增量并入，导出验证时能看到新增的slaProperties与roles。

场景 3：替换既有契约（Replace）

1. 进入一张已有数据契约的表；
2. 点击Manage > "Import ODCS"；
3. 上传合法文件；
4. 选择"Replace existing"选项；
5. 校验替换警告展示数据丢失影响；
6. 点击Import；
7. 校验旧契约被删除、新契约被创建。

替换模式的测试断言值得注意：Replace mode preserves identity fields (ID, name, FQN) but replaces content—— 即身份字段（ID、name、FQN）保留，内容整体替换。导入valid-basic.yaml（无 SLA/roles）后，SLA 卡片不再显示，导出文件包含slaProperties: []与roles: []空数组（见 ODCSImportExport.spec.ts）。

场景 4：错误处理

1. 逐个上传非法示例文件（invalid-missing-apiversion.yaml、invalid-malformed-yaml.yaml等）；
2. 校验展示相应的错误提示；
3. 校验非法文件下Import 按钮被禁用。

场景 5：文件类型校验

1. 尝试上传invalid-not-yaml.txt；
2. 校验文件被拒绝（仅接受.yaml/.yml扩展名）。

场景 6：多对象契约导入

1. 进入一张表（如 sample_data 的dim_address）；
2. 点击"Add Contract" > "Import from ODCS"；
3. 上传valid-multi-object.yaml或sample-data-multi-object.yaml；
4. 校验出现"This contract contains multiple schema objects"提示；
5. 校验对象选择下拉框展示全部 schema 对象（如dim_address、dim_customer、dim_location）；
6. 校验未选择对象时 Import 按钮禁用；
7. 选择与目标表匹配的 schema 对象（如dim_address表选择dim_address）；
8. 校验基于所选对象执行校验；
9. 点击Import；
10. 校验契约仅使用所选对象的 schema 创建。

场景 7：基于 sample_data 的验证

1. 以 sample_data 数据启动 OpenMetadata；
2. 进入sample_data.ecommerce_db.shopify.dim_address；
3. 上传sample-data-dim-address.yaml；
4. 校验 schema 校验通过（所有列均匹配）；
5. 导入并校验契约拥有正确的 schema 定义。

自动化测试：从手工步骤到 Playwright 脚本

上述手工步骤在仓库中已完全自动化。测试入口 ODCSImportExport.spec.ts（共 2200+ 行）通过@import-exporttag 组织用例，核心交互封装在 utils/odcsImportExport.ts 中：

• navigateToContractTab：进入实体页并点击[data-testid="contract"]标签；
• openODCSImportDropdown：根据有无既有契约自适应点击add-contract-button或manage-contract-actions；
• importODCSYaml(page, yamlContent, filename, options?)：打开import-contract-modal，通过file-upload-input注入文件内容（mimeType: 'application/yaml'），如存在既有契约则选择import-mode-merge/import-mode-replace单选按钮，随后监听接口响应并点击import-button。

值得注意的是 importODCSYaml 中关于 API 端点的注释，它揭示了前后端契约：

• 新建契约：POST /api/v1/dataContracts/odcs/yaml；
• 合并 / 替换：PUT /api/v1/dataContracts/odcs/yaml（带 mode 参数）。

即导入过程实际是「前端解析文件 → 调用后端 ODCS 转换接口 → 落库」，而转换与校验的核心逻辑位于后端 ODCSConverter.java（1200+ 行，提供toODCS()导出与对应的 ODCS→OpenMetadata 导入转换，覆盖 ODCS 的 DataContract、Description、SlaProperty、QualityRule、SchemaElement、Role、TeamMember 等全部 v3.1.0 结构）。验证导入成功的方式是等待toastNotification(page, 'ODCS Contract imported successfully')提示，这与 UI 上真实的成功 Toast 一致。

测试样本的组织建议

从该目录的设计可以提炼出组织 ODCS 测试样本的三条实践原则，供后续扩展参考：

1. 按「合法 / 兼容 / 非法」三分类组织：合法样本验证正常路径，sample_data 兼容样本验证真实表结构匹配，非法样本验证每条校验分支（缺字段、错值、语法错误、空文件、类型拒绝）；
2. 用文件名表达意图：valid-*、invalid-*、sample-data-*前缀让测试与手工验证都能快速定位；README 中的表格同时充当「文件 → 覆盖点」的可追溯矩阵；
3. 一个样例聚焦一个特性：valid-with-timestamps.yaml专测时间类型与时区、valid-quality-rules.yaml专测质量规则、valid-multi-object.yaml专测多对象——特性隔离让失败用例能精准定位到具体功能分支。

小结

ODCS v3.1.0 导入是 OpenMetadata 数据契约能力对接行业标准的关键路径：前端提供「新建 / 合并 / 替换」三种导入模式与多对象选择、文件类型校验等交互，后端由ODCSConverter完成双向映射并把质量规则落地为测试用例。odcs-examples目录中成体系的合法、非法与 sample_data 兼容样例，既是手工验收的即用素材，也是 Playwright 自动化回归的测试数据源，建议在接入或改造 ODCS 导入功能时直接复用这套样本与测试脚本（ODCSImportExport.spec.ts、utils/odcsImportExport.ts），快速获得完整覆盖。

【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata