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: true

The 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.
  • **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.

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

How to use the Data Contract Generator: step by step

  1. Load a sample of your file in the Data Contract tool.
  2. Review the suggested rules and switch some on or off.
  3. Download the ODCS YAML.
  4. 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.