Create and edit contracts

With Git-managed contracts, you define your expectations as code using YAML. This gives you full control over how your data is validated, and allows you to manage contracts just like any other code artifact: versioned, tested, and deployed via Git.

To learn all about the structure and supported features, refer to the full specification in the Contract Language reference.

The contract structure includes:

• Dataset and column structure

• Available check types (missing, invalid, duplicate, freshness, etc.)

• Filters (dataset-level and check-level) — Optional

• Threshold configuration — Optional

• Use of variables — Optional

• Scheduling — Optional

• ...and more

Create a contract

Creating a contract requires having installed the soda package using the Private PyPi installation flow available both for Team and Entreprise license, unless you are using an Agent.

Need access to the private PyPI? Please contact us.

You can create a contract template (contract.yml) by running:

soda contract create -f contract.yml -ds ds_config.yml -d <DATA_SOURCE>/<DATABASE>/<SCHEMA>/<TABLE>

Field	Mandatory	Notes
-f		The path to the file to be created. If the contract should live in a different directory than the current one, provide it. E.g. contract.yml Name of the file (if in same directory) /path/to/contract.yml Path to the file to be created.
-ds		The data source configuration file. E.g. ds_config.yml
-d		Fully qualified name of the dataset, slash separated. E.g. <DATA_SOURCE>/<DATABASE>/<SCHEMA>/<TABLE>
-sc		A Soda Cloud configuration file path. E.g. sc_config.yml
-a		Executes contract verification on Soda Agent instead of locally in this library.

This will create a contract skeleton based on data source metadata. For example, a contract skeleton generated for a dataset retail_orders in a PostgreSQL data source looks as follows:

contract.yml

dataset: <DATA_SOURCE>/<DATABASE>/<SCHEMA>/<TABLE>
columns:
  - name: order_id
    data_type: character varying
    character_maximum_length: 50
  - name: product_id
    data_type: character varying
    character_maximum_length: 50
  - name: customer_id
    data_type: character varying
    character_maximum_length: 50
  - name: order_quantity
    data_type: integer
  - name: discount
    data_type: real
  - name: shipping_address
    data_type: character varying
    character_maximum_length: 64
  - name: total_order_value
    data_type: real
checks:
  - schema:

You can edit this data contract and add the necessary checks by modifying the file contract.yml.

Get the most out of your data contracts: head to the Contract Language reference to learn more.

Test your contract

Before publishing or verifying your contract, you can run a test command to ensure the contract is correctly defined and points to a valid dataset.

soda contract test --data-source ds_config.yml --contract contract.yml

This will:

• Validate the YAML syntax

• Confirm that the referenced dataset exists

• Check for any issues with variables, filters, or structure

Run this as part of your development workflow or CI to catch errors early.

Verify your contract

Before publishing your contract, you may want to execute it to verify that it runs correctly.

Read more about how to Verify a contract

Publish the Contract

If you have Soda Cloud, once your contract is finalized and tested, you can publish it to Soda Cloud, making it the authoritative version for verification and scheduling.

This action requires the "Manage contract" permission on the dataset; the user is identified based on the API key provided in the Soda Cloud configuration.

Learn more about permissions here: Dataset Attributes & Responsibilities

soda contract publish --contract contract.yml --soda-cloud sc.yml

Learn how to connect the CLI to Soda Cloud: Connect to Soda Cloud

Publishing:

• Uploads the contract to Soda Cloud

• Makes it available for manual, scheduled, or programmatic verifications

• Enables visibility and collaboration through the UI

Once published, the contract becomes the source of truth for the dataset until a new version is published.

You’re now ready to start verifying your contract and monitoring your data.

---

You are not logged in to Soda and are viewing the default public documentation. Learn more about Documentation access & licensing.