Introduction
Data contracts let you define data quality and observability rules directly in your source code. You define what correct data looks like using an open format (YAML), so there is no vendor lock-in. Every team can create their own contracts in any repository in the data stack, so they scale naturally across your organization. Foundational then collects contract definitions from across all your repositories and evaluates them continuously.
The contracts are always part of your codebase, giving you full revision history, change ownership, and code reviews. This means that each team has full visibility of who defined a rule, who changed it, and when.
Contract rules cover four areas:
Schema rules: Defines which columns exist in a table and their data types. Adding or removing a column or changing a data type can trigger a contract violation.
Business rules: Establishes required fields, allowable value ranges, and key uniqueness.
Anomaly rules: Sets thresholds for unexpected changes in data, such as a significant drop in a table row count.
SLA rules: Defines the frequency for scheduled data updates. For example, a table that needs to update daily but only updates every two days violates its SLA.
You define upfront what correct data looks like. Foundational flags code and data violations and displays the findings on the Data Contracts tab on the Data Quality page.
When you write data contracts in VS Code or IntelliJ, Foundational provides a schema definition that enables autocompletion and inline validation directly in your IDE. You can author contracts accurately without having to look up or reference the Foundational contract schema. For configuration details, see the section Set up data contract schema validation in your IDE.
How it works
Foundational continuously monitors your data for violations of your data contracts. It monitors changes across both your operational and analytical data stacks, covering:
Upstream engineering changes
Models and pipelines running in your warehouse
When a violation occurs, Foundational flags it on the Data Contracts tab, where you can review overall contract metrics, including covered assets, contract rules, and active violations.
Code violations
Foundational analyzes incoming code changes against your contract rules and flags violations during code review before anything reaches production. Teams can then review, act on, or reject the change before it causes an issue.
Data violations
Foundational also scans your data every few hours to detect violations unrelated to code changes. These violations show on the Data Contracts tab even when there are no actual or proposed code changes. Some contract rules can only produce violations this way. Freshness anomalies, for example, are only detectable against actual data.
Here are two examples of how both detection types work:
Detection type | Violations shown in the Data Contracts tab |
Code-level detection | Contract A specifies that a status field accepts only four values. |
Runtime detection | Contract B specifies that a table updates every hour. |
Data Contracts use cases
Use the Data Contracts tab to perform these actions. To see the steps, go to Actions.
Data Contracts UI
You can find data contract metrics and information on violations on the Data Contracts tab on the Data Quality page. There are three main sections.
Data Contracts tab overview
① Metrics and search
② Contract rows: Expand to view the Contract Definition for each contract
③ Violations: Expand for details
Metrics and Expanded Contract Row
① Metrics: Covered Assets, Contract Rules, Violations
② Search and filter by: Status, Reset All.
③ Click the Contract Sources link to view or edit connected repositories.
④ Contract list columns: Enforcement Status, No. of Rules, Violations, Version, and Last Modified Date.
⑤ Expanded contract row: Visible when there are contract violations. Click a row to expand. Description and Contract Definition.
⑥ Click the File name link to open the source file in your repository.
Violations
Visible when there are violations.
① Violations table: Issue, Downstream Impact, Detected, Introduced by. Click the chevron to expand a violation row. The Introduced by column is blank if Foundational cannot tie the violation to a specific change.
② Explore Change: Click to open the Impact Analysis page and view either code or non-code changes that caused the violation.
③ Issue Description: Shows which contract rule failed, including table and platform details.
④ Mute Issue: Mutes an issue. Once muted, the issue no longer shows as a violation in the UI.
Set up data contract schema validation in your IDE
Foundational provides a schema definition that VS Code and IntelliJ can use to validate and autocomplete data contracts as you write them. As you type, the editor suggests field names, valid values, required properties, and flags errors before you commit.
Prerequisites
VS Code: Install the YAML extension by Red Hat.
IntelliJ / PyCharm: No extension needed. Built-in YAML and JSON schema support is included.
As you write, your editor provides:
Autocompletion: Field names, enum values, and nested structures appear as suggestions
Inline validation: Missing required fields, incompatible types, and invalid values are highlighted directly in the editor
Hover documentation: Field descriptions appear inline when you hover over a property
Schema validation
Once configured, the editor validates every contract file automatically.
Schema autocomplete
To set up data contract schema validation:
Open your data contract YAML file in your IDE.
Add the following comment as the first line of the file:
# yaml-language-server: $schema=https://app.foundational.io/api/v1/datacontracts/schema
Save the file. Your editor now validates and autocompletes against the Foundational contract schema.
Actions
Review data contract status
Review data contract status
From the menu pane, open the Data Quality page.
Click the Data Contracts tab.
Review the metrics at the top of the page: Covered Assets, Contract Rules, Violations.
To filter by enforcement status, click Status and select a filter.
To reset filters, click Reset All.
Click a contract name to view the details:
Description: Plain text description of the contract
Contract Definition: The version-controlled YAML file sourced from your repository
The Contract Sources link (right) opens the connected repository.
Investigate data contract violations
Investigate data contract violations
On the Data Contracts tab, click a contract name to view the details.
Scroll to the Violations table. For each violation, review:
Issue: The type of violation detected
Downstream Impact: Assets affected by the violation
Detected: When the violation was first detected
Introduced by: The change that introduced the violation
Open the data contract source code
Open the data contract source code
On the Data Contracts tab, click a contract name to view the details.
Review the contract source code in the Contract Definition section. The YAML displays inline without leaving the page.
To open the source file directly in your repository, click the File name link on the right above the YAML code.
Explore a change that caused a violation
Explore a change that caused a violation
On the Data Contracts tab, click a contract name to view the details.
Scroll to the Violations table.
In the Introduced by column, click Explore Change to open the Impact Analysis page and view the change that caused the violation.
Mute an issue
Mute an issue
On the Data Contracts tab, click a contract name to view the details.
Scroll to the Violations table and click the chevron next to a violation to expand it.
Click Mute Issue. Once muted, the issue no longer shows as a violation in the UI.
Set up data contract schema validation
Set up data contract schema validation
Open your data contract YAML file in your IDE.
Add the following comment as the first line of the file:
# yaml-language-server: $schema=https://app.foundational.io/api/v1/datacontracts/schema
3. Save the file. Your editor now validates and autocompletes against the Foundational contract schema.