Data Contract Template (ODCS YAML): Copy It and Learn What Every Line Means
People searching for a data contract template want a file they can copy, change and put in a repository. Here is one in the Open Data Contract Standard (ODCS) format, produced by the Data Contract tool from a small orders file, with every part explained. You can use it as it is, or load your own file and get a template that already has your column names.
Open the Data Contract Generator
The template
This contract describes an orders table with five columns. It was generated from a sample file, then two of the optional rules (valid values and ranges) were switched on.
apiVersion: v3.1.0
kind: DataContract
id: 8730c8c8-d0ea-4a32-a866-d4d4f32c8c3f
name: orders
version: 1.0.0
status: draft
schema:
- name: orders
logicalType: object
physicalType: table
quality:
- id: orders_row_count
metric: rowCount
mustBeGreaterOrEqualTo: 1
- id: orders_no_duplicate_rows
metric: duplicateValues
mustBe: 0
arguments:
properties:
- order_id
- customer_email
- status
- amount
- order_date
properties:
- name: order_id
logicalType: integer
required: true
unique: true
- name: customer_email
logicalType: string
required: true
logicalTypeOptions:
pattern: ^[^@\s]+@[^@\s]+\.[^@\s]+$
- name: status
logicalType: string
required: true
quality:
- id: status_valid_values
metric: invalidValues
mustBe: 0
arguments:
validValues:
- paid
- pending
- refunded
- name: amount
logicalType: number
required: true
logicalTypeOptions:
minimum: 10
maximum: 92.5
- name: order_date
logicalType: date
required: trueThe id above is a random identifier the tool generated. Give your own contract its own id and keep that id when you update the file.
What each part means
The header
- **apiVersion** is the version of the standard the file follows (here v3.1.0).
- **kind: DataContract** says what the file is, so other tools can recognise it.
- **id** identifies this contract. Keep it stable when you change the contract later.
- **name** is the dataset the contract is about.
- **version** is the version of your promise. See data contract versioning for when to change it.
- **status** is a label for where the contract stands. The tool writes `draft`; change it once the producer and the consumers agree.
The schema: one table, then its columns
- **schema** lists the tables. This contract has one, `orders`.
- **properties** are its columns. Each has a **name** and a **logicalType**: string, integer, number, boolean, date or timestamp.
- **required: true** means the column may never be empty.
- **unique: true** means no two rows may share a value. The tool turns this on only for a column that looks like an ID.
- **logicalTypeOptions** holds the limits that go with a type: `minimum` and `maximum` for numbers and dates, `pattern` for text, and lengths.
The quality rules
- **quality** is a list of checks, each with an **id**, a **metric** and what it **mustBe**.
- `rowCount` with `mustBeGreaterOrEqualTo: 1` says the file must not be empty.
- `duplicateValues` with `mustBe: 0` over all five columns says no row may appear twice.
- `invalidValues` with a list of `validValues` says the status must be one of the values listed.
Make it yours
- Open the Data Contract tool and load a sample of your own file (CSV, Excel, JSON, Parquet or Avro).
- Read the suggested rules. Switch off any you would not defend, and switch on the ones you would, such as valid values for a status column.
- Download the contract as ODCS YAML and keep it in the same repository as the code that produces the data.
- To get the same rules as dbt tests, save it as a dbt `schema.yml` instead. See from data contract to dbt tests.
Check the template against a file
A contract only helps if something checks it. In the tool's Validate tab, drop a new file and the contract, and it lists each rule as pass or fail, with how many rows break it and example rows. The article on validating a vendor CSV before loading it shows the output.
Limits of a generated template
- The rules describe the one file you loaded. They are a first draft, not the truth about all future files.
- The tool reads rules it can run. Other checks in a contract written elsewhere, such as SQL checks, are listed as warnings and are not run.
- The standard itself is larger than this template. For fields such as owners, servers, SLAs and descriptions, see the ODCS documentation and add them by hand.
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 example and how to validate a CSV
- Data contract rules explained
- ODCS data contract generator
How to use the Data Contract Generator: step by step
- Load a sample of your file in the Data Contract tool.
- Review the suggested rules and switch some on or off.
- Download the ODCS YAML.
- Validate new files against it.
When to use the Data Contract Generator
- Starting a data contract from a working example
- Learning what each ODCS field does
- Generating a template from your own file
- Keeping a contract next to the code
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
Is there a free data contract template?
Yes. The template above is in ODCS YAML and was produced by the free Data Contract tool. You can copy it, or load your own file and get one with your own columns.
Which standard does the template follow?
The Open Data Contract Standard (ODCS), version 3. Other tools that read ODCS can use the file.
What goes in a data contract?
The columns and their types, which values may be empty or must be unique, any allowed values or ranges, and checks on the whole table such as a minimum number of rows.
Can I add owners and SLAs?
The standard supports them, and you can add them by hand in the YAML. The tool writes the schema and the quality rules it can check.
Is my file uploaded?
No. The file is processed in your browser and is not uploaded to our servers.
Tip: Delete any rule you cannot explain in one sentence. A short contract that people trust beats a long one they ignore.