Managing Data Contracts

A data contract is a formal agreement between data producers and data consumers that defines the structure, quality, and expected behavior of a data product. It ensures that both parties have a shared understanding of the data’s format, reliability, and usage expectations.

The required data contract acts as a terms and conditions document for using a data product. It outlines the responsibilities of the data producer and the expectations of subscribers regarding the content and quality of the data. You can provide multiple types of contracts to the data product.

There are four ways to provide a data contract:

  • Upload a file: Submit an existing contract document.
  • Enter a URL: Link to a hosted version of the contract.
  • Import a YAML file: Upload a YAML file that contains the contract
  • Create a new contract: Generate a new contract manually or using a predefined template.

Upload a file

To upload a file as a data contract:

  1. On the data product page, select the Data contract (required) tab.
  2. Select Upload file.
  3. Drag and drop or upload an existing contract document that is in a PDF file format.
  4. Enter a name for the data contract and select Save.

Enter a URL

To upload a URL:

  1. On the data product page, select the Data contract (required) tab.
  2. Select Enter URL.
  3. Enter a URL that is valid and secure.
  4. Enter a name for the data contract and select Save.

Import a YAML file

To import a YAML file to create a data contract:

  1. From the data product page, click the Data contract (required) tab.
  2. Click Create contract and select Import from YAML.
  3. Upload a YAML file or paste the YAML code.
  4. To ensure the YAML file is compliant to the Open Data Contract Standard versions 2.2.0–3.1.0, click Validate. After the file is validated, click Next to configure your data product.
  5. Select a domain for your data contract. If a matching domain exists in Data Product Hub, it is listed. Otherwise, a warning message appears if the domain specified in the YAML file is not available in Data Product Hub.
  6. Select a connection for your assets and validate it on the server. If a connection is not available in Data Product Hub, you can create a new connection by clicking Create new connection. If the connection is not verified, enter the connection credentials and verify the connection.
  7. Click Import.

Create a data contract

To create a new data contract:

  1. On the data product page, select the Data contract (required) tab.
  2. Select Create contract and you have two options:
    1. Create new - A new contract from scratch without generic input.
    2. Create from template - Generic information is already prepopulated on the template, and you can edit the fields as needed.
  3. In the Overview tab, enter the required Name and Version of the data contract.
  4. Enter the remaining fields that you think are necessary for your data contract and select Save. For more details about each field see the Understanding the data contract fields section.
  5. After creating the data contract, download it as a YAML file and validate the contract by using data contract testing tools such as Data Contract CLI, Soda, and others.
  6. Update the contract test status. The test status can be updated using the DPH API. This allows the results of the test (e.g., pass/fail outcome, timestamp, and any additional messages) to be reflected in the DPH UI under the Tests tab.
    1. DPH API to be used: /data_product_exchange/v1/data_products/-/releases/RELEASE_ID/contract_terms/CONTRACT_TERM_ID
    2. Example of using DPH API:
      curl -X 'PATCH' \ 'https://api.dataplatform.cloud.ibm.com/data_product_exchange/v1/data_products/-/releases/4e2493da-235d-4bdd-a5b2-a971e62cad21%4087836f09-d69d-42e9-8c9d-c7335b6e8c8f/contract_terms/d2af5430-42cf-4f81-b4a0-b5ba97e2043e%4087836f09-d69d-42e9-8c9d-c7335b6e8c8f' \ 
    -H 'accept: application/json' \ 
    -H 'Authorization: Bearer <token> ' \ 
    -H 'Content-Type: application/json-patch+json' \ 
    -d '[ { "op": "add", "path": "/contract_test", "value": { "status": "pass", "last_tested_time": "05-12-2025", "message": "All tests passed" } } ]'

The domain of the data contract will be inherited or derived from the data product, so that the data contract will have the same domain information as the data product.

Create a data contract template

To create a new data contract template:

  1. In the My Work page and go to the Data contract templates tab.
  2. Select New data contract template and you have three options:
    1. Create a new template
    2. Use an existing template
    3. Import from YAML file by uploading a YAML file or pasting the YAML code
  3. Enter or edit the remaining fields that are necessary for the data contract and select Save.
  4. The new template will be listed in the data contract templates tab with the other templates you have created.

Testing Data Contracts

  1. From the data product details page, click the Data Contract tab and go to the Tests section.
  2. Select a project to run the data contract test and click Run Test.
  3. After the data contract testing is initiated, click the refresh icon in the test summary section to see the test results.
  4. Review the test summary, which displays the following information:
    • Status of the test: queued, running, passed, or failed
    • Date when the test last ran
  5. Review the test results table, which displays the following information:
    • Status of the test for each data item: error or analyzed
    • Data quality rule that was tested against the data item
    • Data item in the project
    • Records returned is the number of rows returned that follow data quality rule.

How to onboard Data Product Hub to generative AI

In order to use the Text2SQL service, the Administrator must perform a one-time setup to enable Generative AI settings in DPH:

  1. Navigate to the Configuration and Settings page and click the Generative AI tab.
  2. If the Generative AI service is available to your organization, select the Enable Text2SQL option.

Learn more

Managing Data Product Hub