Data Contract Rules Explained: Required, Unique, Allowed Values, Range and More
A data contract is only as good as its rules. Some rules are safe almost everywhere. Others look sensible on one sample file and then fail every good file that arrives next month. This guide goes through the nine rules the Data Contract tool can write and check, what each one catches, and when it is a mistake. The examples come from a real run on a small orders file.
Open the Data Contract Generator
The nine rules at a glance
| Rule | It says | Safe to switch on by default? |
| --- | --- | --- |
| Type | The column is an integer, number, string, date, timestamp or boolean | Yes |
| Required | The column is never empty | Yes, for columns that really are required |
| Unique | No value appears twice | Only for real IDs |
| Allowed values | The value is one of a list | Only for a fixed list |
| Range | The value is between a minimum and a maximum | Rarely |
| Length | The text is between a minimum and a maximum number of characters | Rarely |
| Pattern | The text matches a pattern such as an email address | When the format is well known |
| Minimum rows | The file has at least N rows | Yes |
| No duplicate rows | No row appears twice | Yes, when rows should be distinct |
The rules, one by one
Type
Catches a column that changed shape: a date that turns into text, or a number column that gets the word `N/A`. In the example run, a row with the date `04/02/2026` failed `order_date must be a date`, because the contract expects `2026-04-02`. Type rules are the most useful and the least risky.
Required
Catches missing values in columns that must be filled. A row with an empty `customer_email` failed `customer_email must never be empty`. Do not set it on a column that is legitimately sometimes empty, such as an optional coupon code.
Unique
Catches duplicated keys, which silently inflate totals after a join. The tool switches it on only for an ID-like column. Do not set it on a date or a name: two orders can share a date.
Allowed values
Catches a value outside a fixed list. In the run, `status` was `paid`, `pending` or `refunded` in the sample, and a delivery with `shipped` failed `status must be one of: paid, pending, refunded`. This is the rule that catches a new category introduced upstream without telling anyone. It is also off by default: the list from one sample may be incomplete, so a new valid value would fail. Add it only when the list is truly fixed.
Range
Catches impossible numbers and dates, such as a negative amount. In the run, `amount must be between 10 and 92.5` failed on `-5`, which is a real problem. But the same rule made from the sample also set `order_id` between 1001 and 1012, and a later delivery with `order_id` 2001 failed it, although 2001 is a perfectly good ID. The range came from a sample, not from a business rule. This is why ranges start switched off. Use a range only when you know the real limit, such as a percentage between 0 and 100.
Length
Catches truncated or runaway text, such as a phone number cut short. A length taken from one sample (an email of 17 to 18 characters) would fail most real emails, so it starts off. Set it from the database column size or a known format, not from a sample.
Pattern
Catches text that does not look right. The tool recognises some common formats, such as email addresses, and offers a pattern for them. A pattern is strict: check it against several real values before relying on it.
Minimum rows
Catches an empty or nearly empty file, the classic sign that an export job failed quietly. A minimum of 1 is a safe start; raise it if you know the usual size.
No duplicate rows
Catches a file loaded twice or a join that multiplied rows. It compares whole rows, so it will not catch two rows that share a key but differ elsewhere. That is what the unique rule on the key is for.
How to choose
- Start with the safe four: type, required (where it is true), minimum rows and no duplicate rows.
- Add unique for the real key.
- Add allowed values, ranges, lengths and patterns one at a time, only where you can explain the rule to someone else.
- Run the contract against two or three past files before you rely on it. If good files fail, the rule is wrong, not the file.
Where these rules stop
These rules check one file at a time. They do not compare two tables, check that a value exists in another table, or check freshness over time. Rules from a contract written elsewhere that the tool cannot run, such as SQL checks, are listed as warnings and are not checked.
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
- Data contract template (ODCS YAML)
- Validate a vendor CSV before loading it
- A startup data stack on a zero budget
How to use the Data Contract Generator: step by step
- Generate a contract from a sample file.
- Keep the safe rules switched on.
- Add risky rules only where you know the real limit.
- Test the contract on past files.
When to use the Data Contract Generator
- Choosing which data quality rules to write
- Understanding why a rule failed
- Avoiding rules that fail good files
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 rules can a data contract have?
This tool writes and checks nine: type, required, unique, allowed values, range, length, pattern, minimum rows and no duplicate rows.
Why are range and allowed-value rules switched off by default?
They are guessed from one sample and are easy to get wrong. A range or list taken from one file can fail perfectly good files that arrive later.
What is the difference between required and unique?
Required means a value must be present. Unique means no value may appear twice. A key is usually both.
Which rule catches an empty file?
The minimum rows rule. A value of 1 catches a file that has a header and no data.
Can it check one table against another?
No. The rules check one file at a time.
Tip: When a rule fails a file you know is good, believe the file and fix the rule. A rule from one sample is a guess.