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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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:

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

FAQ’s

  1. 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.
  2. 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.
  3. Who owns the data contract? Ownership remains with data engineers.
  4. Can we buy data contracts platform? Wait until March this year. You can explore decube.io
  5. 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

What is a Data Trust Platform in financial services?
A Data Trust Platform is a unified framework that combines data observability, governance, lineage, and cataloging to ensure financial institutions have accurate, secure, and compliant data. In banking, it enables faster regulatory reporting, safer AI adoption, and new revenue opportunities from data products and APIs.
Why do AI initiatives fail in Latin American banks and fintechs?
Most AI initiatives in LATAM fail due to poor data quality, fragmented architectures, and lack of governance. When AI models are fed stale or incomplete data, predictions become inaccurate and untrustworthy. Establishing a Data Trust Strategy ensures models receive fresh, auditable, and high-quality data, significantly reducing failure rates.
What are the biggest data challenges for financial institutions in LATAM?
Key challenges include: Data silos and fragmentation across legacy and cloud systems. Stale and inconsistent data, leading to poor decision-making. Complex compliance requirements from regulators like CNBV, BCB, and SFC. Security and privacy risks in rapidly digitizing markets. AI adoption bottlenecks due to ungoverned data pipelines.
How can banks and fintechs monetize trusted data?
Once data is governed and AI-ready, institutions can: Reduce OPEX with predictive intelligence. Offer hyper-personalized products like ESG loans or SME financing. Launch data-as-a-product (DaaP) initiatives with anonymized, compliant data. Build API-driven ecosystems with partners and B2B customers.
What is data dictionary example?
A data dictionary is a centralized repository that provides detailed information about the data within an organization. It defines each data element—such as tables, columns, fields, metrics, and relationships—along with its meaning, format, source, and usage rules. Think of it as the “glossary” of your data landscape. By documenting metadata in a structured way, a data dictionary helps ensure consistency, reduces misinterpretation, and improves collaboration between business and technical teams. For example, when multiple teams use the term “customer ID”, the dictionary clarifies exactly how it is defined, where it is stored, and how it should be used. Modern platforms like Decube extend the concept of a data dictionary by connecting it directly with lineage, quality checks, and governance—so it’s not just documentation, but an active part of ensuring data trust across the enterprise.
What is an MCP Server?
An MCP Server stands for Model Context Protocol Server—a lightweight service that securely exposes tools, data, or functionality to AI systems (MCP clients) via a standardized protocol. It enables LLMs and agents to access external resources (like files, tools, or APIs) without custom integration for each one. Think of it as the “USB-C port for AI integrations.”
How does MCP architecture work?
The MCP architecture operates under a client-server model: MCP Host: The AI application (e.g., Claude Desktop or VS Code). MCP Client: Connects the host to the MCP Server. MCP Server: Exposes context or tools (e.g., file browsing, database access). These components communicate over JSON‑RPC (via stdio or HTTP), facilitating discovery, execution, and contextual handoffs.
Why does the MCP Server matter in AI workflows?
MCP simplifies access to data and tools, enabling modular, interoperable, and scalable AI systems. It eliminates repetitive, brittle integrations and accelerates tool interoperability.
How is MCP different from Retrieval-Augmented Generation (RAG)?
Unlike RAG—which retrieves documents for LLM consumption—MCP enables live, interactive tool execution and context exchange between agents and external systems. It’s more dynamic, bidirectional, and context-aware.
What is a data dictionary?
A data dictionary is a centralized repository that provides detailed information about the data within an organization. It defines each data element—such as tables, columns, fields, metrics, and relationships—along with its meaning, format, source, and usage rules. Think of it as the “glossary” of your data landscape. By documenting metadata in a structured way, a data dictionary helps ensure consistency, reduces misinterpretation, and improves collaboration between business and technical teams. For example, when multiple teams use the term “customer ID”, the dictionary clarifies exactly how it is defined, where it is stored, and how it should be used. Modern platforms like Decube extend the concept of a data dictionary by connecting it directly with lineage, quality checks, and governance—so it’s not just documentation, but an active part of ensuring data trust across the enterprise.
What is the purpose of a data dictionary?
The primary purpose of a data dictionary is to help data teams understand and use data assets effectively. It provides a centralized repository of information about the data, including its meaning, origins, usage, and format, which helps in planning, controlling, and evaluating the collection, storage, and use of data.
What are some best practices for data dictionary management?
Best practices for data dictionary management include assigning ownership of the document, involving key stakeholders in defining and documenting terms and definitions, encouraging collaboration and communication among team members, and regularly reviewing and updating the data dictionary to reflect any changes in data elements or relationships.
How does a business glossary differ from a data dictionary?
A business glossary covers business terminology and concepts for an entire organization, ensuring consistency in business terms and definitions. It is a prerequisite for data governance and should be established before building a data dictionary. While a data dictionary focuses on technical metadata and data objects, a business glossary provides a common vocabulary for discussing data.
What is the difference between a data catalog and a data dictionary?
While a data catalog focuses on indexing, inventorying, and classifying data assets across multiple sources, a data dictionary provides specific details about data elements within those assets. Data catalogs often integrate data dictionaries to provide rich context and offer features like data lineage, data observability, and collaboration.
What challenges do organizations face in implementing data governance?
Common challenges include resistance from business teams, lack of clear ownership, siloed systems, and tool fragmentation. Many organizations also struggle to balance strict governance with data democratization. The right approach involves embedding governance into workflows and using platforms that unify governance, observability, and catalog capabilities.
How does data governance impact AI and machine learning projects?
AI and ML rely on high-quality, unbiased, and compliant data. Poorly governed data leads to unreliable predictions and regulatory risks. A governance framework ensures that data feeding AI models is trustworthy, well-documented, and traceable. This increases confidence in AI outputs and makes enterprises audit-ready when regulations apply.
What is data governance and why is it important?
Data governance is the framework of policies, ownership, and controls that ensure data is accurate, secure, and compliant. It assigns accountability to data owners, enforces standards, and ensures consistency across the organization. Strong governance not only reduces compliance risks but also builds trust in data for AI and analytics initiatives.
What is the difference between a data catalog and metadata management?
A data catalog is a user-facing tool that provides a searchable inventory of data assets, enriched with business context such as ownership, lineage, and quality. It’s designed to help users easily discover, understand, and trust data across the organization. Metadata management, on the other hand, is the broader discipline of collecting, storing, and maintaining metadata (technical, business, and operational). It involves defining standards, policies, and processes for metadata to ensure consistency and governance. In short, metadata management is the foundation—it structures and governs metadata—while a data catalog is the application layer that makes this metadata accessible and actionable for business and technical users.
What features should you look for in a modern data catalog?
A strong catalog includes metadata harvesting, search and discovery, lineage visualization, business glossary integration, access controls, and collaboration features like data ratings or comments. More advanced catalogs integrate with observability platforms, enabling teams to not only find data but also understand its quality and reliability.
Why do businesses need a data catalog?
Without a catalog, employees often struggle to find the right datasets or waste time duplicating efforts. A data catalog solves this by centralizing metadata, providing business context, and improving collaboration. It enhances productivity, accelerates analytics projects, reduces compliance risks, and enables data democratization across teams.
What is a data catalog and how does it work?
A data catalog is a centralized inventory that organizes metadata about data assets, making them searchable and easy to understand. It typically extracts metadata automatically from various sources like databases, warehouses, and BI tools. Users can then discover datasets, understand their lineage, and see how they’re used across the organization.
What are the key features of a data observability platform?
Modern platforms include anomaly detection, schema and freshness monitoring, end-to-end lineage visualization, and alerting systems. Some also integrate with business glossaries, support SLA monitoring, and automate root cause analysis. Together, these features provide a holistic view of both technical data pipelines and business data quality.
How is data observability different from data monitoring?
Monitoring typically tracks system metrics (like CPU usage or uptime), whereas observability provides deep visibility into how data behaves across systems. Observability answers not only “is something wrong?” but also “why did it go wrong?” and “how does it impact downstream consumers?” This makes it a foundational practice for building AI-ready, trustworthy data systems.
What are the key pillars of Data Observability?
The five common pillars include: Freshness, Volume, Schema, Lineage, and Quality. Together, they provide a 360° view of how data flows and where issues might occur.
What is Data Observability and why is it important?
Data observability is the practice of continuously monitoring, tracking, and understanding the health of your data systems. It goes beyond simple monitoring by giving visibility into data freshness, schema changes, anomalies, and lineage. This helps organizations quickly detect and resolve issues before they impact analytics or AI models. For enterprises, data observability builds trust in data pipelines, ensuring decisions are made with reliable and accurate information.

Table of Contents

Read other blog articles

Grow with our latest insights

Sneak peek from the data world.

Thank you! Your submission has been received!
Talk to a designer

All in one place

Comprehensive and centralized solution for data governance, and observability.

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
decube all in one image