What is a data contract?

A data contract describes what a table contains, so the people who use the data can rely on it: which columns it has, their data types and what they mean. In Specly it is written from the model, so it describes what the team has actually modeled.

The Open Data Contract Standard (ODCS) is a widely used open standard for data contracts, written as YAML. Data products are covered by a sister standard, the Open Data Product Standard (ODPS).

Do we have to use ODCS?

No. The format for the Git export is chosen per project: Specly JSON, ODCS contracts or both.

Which version of ODCS does Specly use?

Specly writes ODCS 3.2. Every contract starts with apiVersion: v3.2.0 and kind: DataContract.

Data contracts

The data contract comes from the model.

A data contract in Specly is the table as you modeled and documented it – columns, data types, descriptions and status – written as an ODCS file that consumers can read and test against.

dim_customer.odcs.yaml

apiVersion: v3.2.0
kind: DataContract
id: dim_customer
name: dim_customer
version: 1.0.0
status: active
schema:
- name: dim_customer
  physicalType: table
  description: One row per customer, conformed across the CRM and webshop.
  customProperties:
  - property: owner
    value: Customer team
  properties:
  - name: customer_id
    description: Primary key, unique customer identifier
    logicalType: string
    physicalType: uuid
    primaryKey: true
    primaryKeyPosition: 1
  - name: email
    description: Primary contact email address
    logicalType: string
    physicalType: text
  - name: is_active
    description: True if the customer has paid for at least one order in the last twelve months
    logicalType: boolean
    physicalType: boolean

How it fits together

From model to contract in three steps.

1
Model and document
Tables, columns, data types and descriptions are created in Specly, where the team already works on the model. The contract is built from what is there.
2
Decide what maps to what
You decide which fields in Specly correspond to which fields in ODCS. Values without a link are kept as custom properties in the contract, so nothing is lost.
3
Deliver to Git
Each table is written as one .odcs.yaml and each data product as one .odps.yaml, on the same branch as the code.

A standard, not a format of our own

Contracts other tools can read.

An open standard
ODCS is a widely used open standard for data contracts. The files are not tied to Specly.
The tools you want to use
Consumers read the contract directly, and tools such as the Data Contract CLI can use it for validation.
Always in step with the model
Contracts are written from the same model the team edits. There is no separate copy to keep up to date on the side.

Questions and answers

What people often ask.

What is a data contract?: A data contract describes what a table contains, so the people who use the data can rely on it: which columns it has, their data types and what they mean. In Specly it is written from the model, so it describes what the team has actually modeled.
What is ODCS?: The Open Data Contract Standard (ODCS) is a widely used open standard for data contracts, written as YAML. Data products are covered by a sister standard, the Open Data Product Standard (ODPS).
Do we have to use ODCS?: No. The format for the Git export is chosen per project: Specly JSON, ODCS contracts or both.
Which version of ODCS does Specly use?: Specly writes ODCS 3.2. Every contract starts with apiVersion: v3.2.0 and kind: DataContract.

See Specly in action.

Tell us how you work today, and we will show you how Specly could fit in.

Book a demo hei@specly.no

From model to contract in three steps.

Model and document

Decide what maps to what

Deliver to Git

Contracts other tools can read.

An open standard

The tools you want to use

Always in step with the model

What people often ask.

See Specly in action.