Skip to content

Contracts

A contract is a type of test suite that keeps its tests in numbered versions and holds a contract document, which you import and export as an Open Data Contract Standard (ODCS) file. Use a contract when the quality rules for a set of tables are an agreement between the teams that produce the data and the teams that rely on it. Changes are prepared in a draft and previewed against your data, then frozen as the next version, so the agreement never changes without review. The contract document can be shared as an ODCS file with producers, consumers, and other tools, and a Schema Conformance test on each declared table reports when the data drifts from its declared columns and types.

A contract uses the same test types as any test suite, and its tests are edited, run, and investigated the same way. See Contract Versions and Contract Documents for what a contract adds.

Prerequisites

  • A table group. Use an existing table group or create a new one.
  • For the contract to get quality tests and profiling results when you create it, the table group must have been profiled.

Create a contract

  1. Select Test Suites from the menu.
  2. Click Add Test Suite.
  3. Under Type, select Contract.
  4. Enter a Contract Name, unique within the project, and an optional Contract Description.
  5. Select the Table Group for the contract.
  6. Optional. Set Severity, Export to Observability, and Exclude from quality scoring, as for any test suite.
  7. Click Next.

  8. Choose what the contract starts from.

    Leave Start from set to Table group, and select the Tables the contract declares. When the table group has been profiled, choose the Generation Sets for the contract's tests. TestGen fills in the contract from these tables. See What generation fills in.

    Set Start from to ODCS file, choose the ODCS contract file, and review the preview. The file must meet the file requirements.

    • Tests created from the file are locked, so regenerating the contract does not change them.
    • Rules that TestGen cannot check are kept in the contract document, but they never run. See ODCS Mapping Reference.
    • A file whose id another contract in the table group already has is refused. To update that contract, import the file into it, or change the file's id to create a separate contract.

  9. Click Add.

The contract starts with a draft. To make the draft the active version, freeze it.

Regenerate a contract

Regenerate a contract to update its draft from the latest profiling run and the data catalog.

  1. Select Test Suites from the menu.
  2. On the contract, click Regenerate Contract.
  3. Under Regenerate, select what to refresh. Columns and their data types are always refreshed.
    • Tests — Regenerates the tests from the latest profiling run. To change the generation sets, expand Generation Sets under Tests. Locked tests and manually added tests are kept.
    • Profiling results — Functional types, keys, formats, and observed values.
    • Catalog metadata — Descriptions, tags, classification, and the PII, critical data element, and excluded flags.
  4. Click Regenerate Contract.

Warning

Each option you select replaces any edits you made to those fields in the contract document.

Tests and observed values are not refreshed for declared tables that have not been profiled.

Edit a contract's tests and document

Select Test Suites from the menu, and click View N test definitions on the contract.

  • Quality Rules — The contract's tests. Work with them as on the Test Definitions page of any test suite.
  • Contract Metadata — The declared tables and the contract document. See Contract Documents.

Changes are saved to the draft. Other versions are read-only. See Contract Versions.

Run a contract

A contract is run and scheduled like any test suite. Each run checks one of the contract's versions. See Run a version for which version a run checks and which runs update the contract's results.

Reference

What generation fills in

Creating or regenerating a contract fills in its draft from the data catalog and the latest profiling run. For each declared table, it fills in the contract document and the tests.

  • Contract document
    • Column descriptors, with each column's physical and logical types.
    • Profiling results: functional types, the primary key, granularity, string formats, and observed values, such as minimums and maximums. Columns flagged as PII or excluded from testing get no observed values.
    • Catalog metadata: descriptions, tags, classification, and the critical data element, PII, and excluded flags.
  • Tests
    • A Schema Conformance test, when TestGen finds the table in the source.
    • Quality tests from the contract's generation sets, generated from the latest profiling run as for any test suite.

The contract's description and tags come from the table group, and its server entry from the connection.

Run profiling, and then regenerate the contract.

Contract generation set

The Contract generation set generates these test types. Only a contract can use it. A contract can use any other generation set too. See TestGen Test Types for what each test checks.

  • Duplicate Rows
  • Minimum Date
  • Minimum Value
  • Pattern Match
  • Recency
  • Required Entry
  • Required, No Placeholder
  • Row Count
  • Unique Values
  • Value Match

Next steps