Skip to content

Contract Documents

Each contract holds a contract document, which declares the tables the contract covers and describes their columns. Import and export it as an Open Data Contract Standard (ODCS) file to share the contract with the producers and consumers of those tables, or with other tools.

What a contract document holds

  • Declared tables — The tables the contract covers. The contract's tests can target only these tables.
  • Columns — Each declared table's columns with their physical and logical types, profiling results, descriptions, and catalog metadata, such as tags, classification, and the critical data element, PII, and excluded flags.
  • Overview, team, roles, support, service levels, and servers — What the contract is for, who owns it, how to reach them, and where the data lives.
  • Unverifiable rules — Quality rules TestGen cannot check. They are exported with the contract, but they never run. See ODCS Mapping Reference for which rules become tests.

The contract's tests are on the Quality Rules tab, and are added to the document when you export the contract. Each declared table that TestGen finds in the source gets a Schema Conformance test, which reports differences between the table and its declared columns and types.

Creating or regenerating the contract fills in the document from the data catalog and profiling results. Editing the document does not change the data catalog. Every change to the document is saved to the contract's draft. See Contract Versions.

View a contract document

  1. Select Test Suites from the menu.
  2. On the contract, click View N test definitions .
  3. Open the Contract Metadata tab.

Change the declared tables

  1. On the Contract Metadata tab, in the Schema section, click Edit Tables.
  2. Select the tables the contract declares, and click Save.
  3. If you removed a table, confirm in the Remove Tables dialog, and click Remove.

Adding a table declares its columns from the data catalog and adds its Schema Conformance test, and its quality tests when the table has been profiled. Removing a table deletes its tests from the draft.

Edit a section

  1. On the Contract Metadata tab, click Edit in the section you want to change.
  2. Change the fields, and click Save. The save replaces only that section.
Section What you edit
Overview The domain, tenant, tags, purpose, usage, and limitations. TestGen sets the name and status.
Schema A table's or column's description, types, keys, flags, and examples. Select the table or column in the tree first. Values that a quality rule declares show under Declared by Quality Rules. Change them on the rule.
Team The team's name, description, and members
Roles, Support, Service Levels The contract's roles, support channels, and service levels. TestGen does not check service levels.

Servers and Rules TestGen Cannot Check are read-only. Edit them as YAML.

Edit the document as YAML

  1. On the Contract Metadata tab, click Edit as YAML. On a read-only version, the button is View as YAML.
  2. Edit the YAML, and click Save.

Do not change apiVersion, kind, id, version, name, or status, which TestGen sets. status follows the version: draft, active, or deprecated once a later version is frozen. Comments in the YAML are discarded on save.

A quality rule that a TestGen test type checks cannot be added in the YAML. Add it as a test on the Quality Rules tab. A quality rule that no test type checks is saved and marked unverifiable.

Export a contract

  1. Select Test Suites from the menu, and click View N test definitions on the contract.
  2. Select the version to export in Version.
  3. Click Export Contract.
  4. Review the document, and click Download.

The file, named such as orders_v3_active.yaml, is the contract document with the version's active tests added as quality rules. Muted tests are left out. See ODCS Mapping Reference for how each test appears.

Import a contract file

Import a contract file to apply changes made outside TestGen to an existing contract. To create a contract from a file, see Create a contract. An import writes to the contract's draft, and creates one when the contract has none. The file's id must match the contract's.

Warning

The file replaces the contract. Each active test that is not in the file is permanently deleted from the draft.

  1. Open the contract's test definitions on the version you can edit: the draft, or the active version when there is no draft.
  2. Click Import Contract.
  3. Choose the ODCS contract file.
  4. Review the preview. It lists the first 500 tests and what the import does with each: create, update, delete, or leave unchanged.
  5. If the import deletes tests, select the confirmation checkbox.
  6. Click Import Contract.

What an import changes

  • Each quality rule and column declaration that a TestGen test type checks becomes a test. Every other quality rule is kept in the contract document, marked unverifiable. See ODCS Mapping Reference.
  • A test in the file updates the existing test with the same rule id, or else with the same test type, table, and column. A test with no match is created.
  • Imported tests are locked, so regenerating the contract does not change them.

Reference

File requirements

  • An ODCS document of version v3.1.0 or v3.2.0, in YAML or JSON, that is valid against that version's schema. TestGen exports v3.2.0.
  • UTF-8 text.
  • A file you upload in TestGen is at most 10 MiB (10,485,760 bytes) by default. To accept larger files, set the TG_CONTRACT_IMPORT_MAX_BYTES environment variable to the size in bytes, up to 18,684,464. See Set Environment Variables.

The same requirements apply to a file you create a contract from.

Next steps