Data Contracts: A Comprehensive Guide

Explore the significance of data contracts, their implementation, and how they foster collaboration among stakeholders in this informative article

By

Jatin Solanki

Updated on

October 10, 2024

Would like to thank Andrew Jones , creator of Data contracts concept and how he has implemented at GoCardless.

A lot has been talked about data contracts since 2022, however the challenge is technical platform or capability but more around culture and how to drive the adoption.

Software Engineers or tech team have been practising standardisation of CI/CD across many years, however we haven’t seen that getting implemented within data teams at scale.

‍

What is a data contract?

In simple terms, its an agreement between Data producers and consumers on expected data values. If any event violates the contract the flow should break and raise notification to relevant stakeholders.

Data contracts defines the structure, semantic layer, data quality checks along with metadata level restrictions if any.

Here is sample YAML of Data contract:


table_name: customer_bookings
version: 1.1
owner: jack_dawson
schema:
  - column_name: tx_date
    type: timestamp
    constraints:
      not_null: true
      no_future_dates: true
  - column_name: customer_email
    type: string
    constraints:
      not_null: true
      check_pii: true
  - column_name: sales_amt
    type: decimal
    constraints:
      not_negative: true
  - column_name: revenue_amt
    type: decimal
    constraints:
      not_negative: true
  - column_name: booking_type
    type: string
    constraints:
      enum: [air, hotel, train]

‍

Who owns the data contract?

It’s usually owned by data engineers since they also are owner of data pipeline and quality of the information flowing to raw-layer.

The biggest question is how did we arrive at the stage of creating YAML on whose instruction data engineers are building this YAML or contracts.

This is where things get litte tricky. ‍

‍

Real-life scenario:

Ryan, a marketing analytics manager, was tasked with aiding his team in utilizing insights for business decision-making. As the company ventured into online business, new data sources like Google Analytics and Facebook Ads were integrated, requiring the creation of new data tables and a performance dashboard for strategy development.

Initially, Ryan coordinated with the data engineering team to incorporate these new sources into the company’s data warehouse. He detailed the required columns and business logic for custom fields, guiding the data engineering team in developing the necessary integration layer and custom logic.

Within a week, Ryan prepared scripts to aggregate data and set up SQL jobs for PowerBI publishing. However, on the tenth day, the marketing team, influenced by a perceived doubling in performance shown on the dashboard, altered their strategy. Four days later, discrepancies were noticed between Google Ads clicks and the dashboard figures, leading to the discovery of a pipeline script bug causing data duplication.

This incident highlighted the importance of data quality for Ryan. He quickly addressed the issue, ensuring that robust data quality measures were implemented across the product to prevent future errors.

‍

Setting the expectation:

Ryan will have detailed discussion with the Data team in laying down the data product expectation.

Some of the pointers he will ensure:

Schema checks: All data types should be followed.
Data quality checks: Duplicate checks, non-negative values for metrics like clicks, CTR, impression etc.
Freshness: Table to be updated every 30 mins.
Masking critcal data — customer address and email should be masked. Check on email format being captured correctly.

Ryan wants to know for any changes in the data-assets which powers the Online performance dashboard product.

Using the above information DE will write the YAML file and enforce in CI/CD pipeline.

Data Contracts reduces the proximity between business and data teams.

‍

How can we implement at scale?

It’s an uphill task and more dependent on cultural and process shift before going and achieving at scale.

For smaller teams, it’s relative easy to deploy changes and enforce critical processes. As company grows in size things starts to get messier.

What we’re about to discuss may not appeal to everyone, but we believe it’s the most effective method to drive adoption and attain scale.

Deploy Data Discovery: The initial step involves deploying data discovery tools to identify and catalog our data assets. This will enable us to understand our existing data landscape and prepare for structure governance.
Create Domains & Assign Ownership: Following the discovery phase, we will create specific data domains and assign ownership. This ensures accountability and clear stewardship for different data segments, which is crucial for maintaining data integrity.
Adding Assets within Domains: Once domains are established, we will proceed with adding assets to each domain. This process includes cataloging datasets and systems under their respective domain owners.
Create Data Products: With the assets in place, we will then create data products. These are curated datasets or analytical models designed to meet specific business requirements.
Filter Assets to Meet Data Products Requirements: It is essential to filter and select the appropriate assets that align with the requirements of our data products. This selection is guided by the relevance and quality of the data.
Apply Validation, Schema, and Metadata Rules: Our next move is to apply validation rules, define schema, and set metadata rules. This step is pivotal in ensuring the data meets our standards and is fit for purpose.
Generate YAML File or Create One: For each data product, we will generate a YAML file that encapsulates the data contract, which includes the schema, metadata, and validation rules.
Enforce via GitHub: Finally, the YAML files will be enforced through GitHub, allowing us to integrate data contract enforcement into our CI/CD pipeline. This ensures that any changes in data are automatically validated against the data contracts, maintaining the integrity and reliability of our data products.

‍

One of the most significant and vital responsibilities is to create a data domain and include appropriate data assets into it. People may get lethargic to link assets in a specific domain, which might slow down the whole process. There is no straight or automated method in bringing all the relevant assets in a given Domain.

‍

How to enforce a Data Contract?

Well, it all depends upon CI/CD practices with an organisation and how Data team leverages on Git like platform.

Suppose you have a YAML file defining the schema of a user database in your project. This data contract specifies fields like userID, name, email, creationDate, and isActive, along with their data types and constraints.

1. Git Branching and Version Control

You have a main branch that represents the stable version of your data contract.
Developers create feature branches (e.g., feature/update-user-schema) for any proposed changes to the data contract.

2. Code Reviews and Merge Requests

Developers submit a pull request (PR) or merge request (MR) to merge their changes into main.
Team members review the changes in the PR to ensure they adhere to data standards and meet the project’s needs.

3. Continuous Integration (CI) Pipeline

When a PR is created, a CI pipeline is triggered.
The CI pipeline performs several checks:
YAML Linting: To ensure the file is syntactically correct and adheres to defined styling standards.
Schema Validation: Using a tool like yamale or jsonschema, the pipeline validates the YAML file against the defined schema. This ensures the changes meet the structural and data type requirements.
Unit Tests: Run any unit tests that verify the logic that depends on this data contract, ensuring the changes don’t break existing functionalities.
If any of these checks fail, the CI pipeline flags the PR as failing, and the developer is notified to make corrections.

4. Documentation and Change Log

The PR description should document what changes were made and why. This serves as a record for future reference.
A change log is updated with details about the changes once the PR is merged.

5. Merging and Deployment

Once all CI checks pass and the PR is approved, it is merged into the main branch.
The updated data contract in the main branch can then be deployed to your data systems or data catalog as needed.

6. Access Control and Security

Access to merge into the main branch is restricted to authorized personnel, such as lead data engineers or project maintainers.
Sensitive data within the YAML file, if any, is handled according to security best practices.

‍

Things to consider:

Defining clear data producers, data consumers are super critical.
Platform or tech is just a channel to drive the process and the shift.
Processes needs to be laid down on driving changes and even proposing new assets for a given data product.
Processes should be build to ensure maximum collaboration before rolling out new data product.
Data Product usually includes a details documentation which explains the process, sometimes glossary etc.
There is a possibility of including transformation code within the data product too.

‍

FAQ’s

Can data consumers write data validation if the platform supports no-low code? Data Consumers can propose validation rules but ultimately data producers have to agree and update the YAML.
Whats the difference between data contracts and data catalog (Discovery)? Data Contracts is more about preventive measures and lets the users know during the code push about the impact on downstream assets.
Who owns the data contract? Ownership remains with data engineers.
Can we buy data contracts platform? Wait until March this year. You can explore decube.io
Share some of examples of data products? Here is the list which can give you some flavour:

Recommender systems.
Profit and Loss Dashboard.
Marketing Campaign Performance Dashboard.

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —

Hope you liked the article, feel free to comment.

Article written by Jatin Solanki | founder of decube (Data trust platform for GenAI era). We will soonbe launching our data contracts module — stay tuned and expect our next updates in March this year.

Learn more about decube

Read other blog articles

Agentic AI in Metadata Management

Agentic AI Metadata Management: Simplify your data systems and maintain reliable data with our expert-driven platform.

By

Kamal

April 8, 2025

Perplexity for Data Management - Decube's AI-Powered Data Trust

Discover why Decube is introducing Perplexity for Data Management—leveraging AI to simplify complex lineage, enhance security, and redefine data governance for the AI era.

By

Jatin S

March 13, 2025

Data Trust - Concept and why we started Decube

Discover why Data Trust is essential for accurate decision-making, AI success, and reliable governance. Explore how Decube unifies data quality, lineage, and governance, delivering measurable ROI by simplifying data management.

By

Kamal

March 13, 2025