Data Contract Example in YAML: Write One and Validate a CSV Against It
Every data team has had the same morning: a pipeline breaks because a column changed type, a field that was never empty is now empty, or a source quietly added a status value nobody planned for. A data contract is the written promise that stops those surprises from being a surprise. Here is what one looks like in practice, and how to make and test one without installing anything.
Open the Data Contract Generator
What a data contract is
A data contract is a short, written agreement about what a dataset must look like. It lists the columns, their types, which values may be empty, which must be unique, which values are allowed, and how many rows to expect. It is stored as a YAML file, so it lives in git next to your code and can be reviewed like code.
The point is not the file. The point is that the producer of the data and the people who depend on it agree on the shape, and that a machine can check the agreement every time new data arrives.
The standard: ODCS
You can invent your own format, and many teams have. I would not. The Open Data Contract Standard (ODCS), published at bitol.io, is an open YAML format that other tools already read. The Data Contract tool on this site writes ODCS version 3, so the file you download is not locked to us.
An example
This is the shape of a small contract for an orders table:
apiVersion: v3.1.0
kind: DataContract
id: 7c1f0e7a-3a6e-4a52-9f0a-1d2b3c4d5e6f
name: orders
version: 1.0.0
status: draft
schema:
- name: orders
logicalType: object
physicalType: table
quality:
- metric: rowCount
mustBeGreaterOrEqualTo: 1
properties:
- name: order_id
logicalType: integer
required: true
unique: true
- name: status
logicalType: string
required: true
quality:
- metric: invalidValues
mustBe: 0
arguments:
validValues: [Pending, Shipped, Delivered, Cancelled]Read it top to bottom. The file is a data contract (kind). The table has at least one row (rowCount). order_id is a whole number, is never empty (required) and never repeats (unique). status is never empty and is one of four values (invalidValues with validValues, where mustBe: 0 means zero violations are allowed).
Generate one from a file
Writing YAML by hand for 40 columns is the part nobody enjoys. Open the data contract generator, load a CSV, Excel, JSON or Parquet file, and it suggests rules from the data: the type of each column, whether any value was empty, whether every value was different, a short list of allowed values, the smallest and largest value, text length, and formats such as email and UUID.
Here is the part I care about as an engineer: these are guesses from one sample. If a column had no nulls in your sample, that is evidence, not a guarantee. So the rules that one file can easily get wrong (lists of allowed values, ranges, lengths) start switched off and are marked "Inferred from sample, review before use". You tick the ones you would defend in a review. Nothing is switched on that you did not see.
Validate a new file
Open the Validate tab, choose the contract you just made (or upload an ODCS YAML file), and load the file you want to check. You get a summary such as "3 of 14 rules failed", then each rule with pass or fail, how many rows break it, and up to five example values with their row numbers.
The checks cover missing and extra columns, empty values, data types, duplicate values, allowed values, minimum and maximum, text length, patterns, a minimum row count, and duplicate rows. You can download the result as an HTML report or a CSV. Big files are checked in a background worker, so the page keeps responding.
Schema drift: the check that pays for itself
If I could keep only one check, it would be the column check. When a column in the contract is missing from the file, the rule fails and that column's other rules are marked skipped rather than silently passing. When the file has a column the contract does not know, it fails too, unless you untick that option. Renamed and dropped columns are the most common cause of broken dashboards, and this catches both before the load.
Data contract or dbt tests?
They are not rivals. dbt tests run inside your warehouse after a model is built. A contract describes the data at the boundary, before it is loaded, and is readable by people and tools that never touch dbt. If you use dbt, the same tool saves your rules as a dbt schema.yml with not_null, unique and accepted_values tests, plus tests from the dbt_utils and dbt_expectations packages for ranges, lengths, patterns and row counts. You can untick the package tests if you want core dbt only. For columns and types alone, the dbt schema.yml generator is the smaller step.
What it does not do
Be clear about the limits, because they decide whether this is enough for you:
- It checks one file at a time in your browser. It does not watch a warehouse, run on a schedule or store contracts.
- It reads one table per contract. If a contract describes several tables, only the first is used and you get a warning.
- It runs the rules listed above. SQL and custom quality rules in a contract written elsewhere are listed as warnings and not checked.
- Suggested rules describe your sample. Review them before you rely on them.
Privacy
Files are read and checked in your browser and are not uploaded. The report you download contains example values from your file, so there is a switch to leave them out before you share it.
Open the Data Contract Generator
Related tool pages
- ODCS Data Contract Generator: Generate an Open Data Contract Standard (ODCS) v3 YAML file from a CSV, Excel, JSON or Parquet file. Edit the rules, then download. Free, in your browser.
- Validate a CSV Against a Schema: Check a CSV or Excel file against a data contract: required values, types, unique columns, allowed values, ranges, patterns and missing or extra columns. Free, in your browser.
Also try
- Validate a CSV against a schema
- ODCS data contract generator
- dbt schema.yml generator
- CSV data quality checker
How to use the Data Contract Generator: step by step
- Open the data contract generator and load a sample file.
- Tick the rules you trust, then download the ODCS YAML or a dbt schema.yml.
- Open Validate, load a new file and read which rules fail.
When to use the Data Contract Generator
- Agree what a dataset must look like with its producer
- Catch schema drift before a load
- Check a vendor file against the agreed format
- Turn a sample into dbt tests quickly
Example
Input: orders.csv: order_id, status, unit_price
Output: kind: DataContract schema: - name: orders properties: - name: order_id logicalType: integer required: true unique: true
Frequently asked questions
What is a data contract?
A written agreement about what a dataset must look like, stored as a YAML file: its columns, types, which values may be empty, which must be unique, which values are allowed and how many rows to expect.
What is the Open Data Contract Standard (ODCS)?
An open YAML format for data contracts published at bitol.io. This tool writes ODCS version 3, so other tools that read ODCS can use the file.
Can I generate a data contract from a CSV?
Yes. Load the CSV (or Excel, JSON or Parquet), review the suggested rules, and download the contract as ODCS YAML or a dbt schema.yml.
How do I validate a CSV against a data contract?
Open the Validate tab, choose your contract or upload an ODCS YAML file, and load the CSV. Each rule shows pass or fail, the number of rows that break it and example values with row numbers.
Are the suggested rules safe to use as they are?
Treat them as a draft. They come from one file. Rules that one sample can get wrong, such as allowed values and ranges, start switched off and are marked for review.
Is my file uploaded?
No. The file is read, profiled and checked in your browser.
Tip: Start with the safe rules (type, required, unique ID, minimum rows) and add ranges and allowed values only after you have checked them against more than one file.