Welcome

Every data pipeline rests on a promise: the data will look like this tomorrow, too. That promise is usually implicit, and it breaks silently when a column is renamed, a type changes, or a table is dropped. Data contracts make the promise explicit, machine-readable, and testable.

In this tutorial you work through a realistic scenario end to end, on your own laptop, at your own pace.

What is a data contract?

Think of it as an API specification (like OpenAPI), but for data. A contract answers:

• Schema: Which tables and columns exist, with which types?
• Semantics: What does order_total mean? In which unit?
• Quality: Which rules must the data fulfill, e.g. "no negative totals"?
• Ownership & support: Who is responsible, and where do I get help?
• Service levels: How fresh is the data, and how long is it retained?

Two open standards

Both standards are developed in the open by Bitol, a Linux Foundation project.

A data product offers its data through output ports, each described by a data contract. A data product that builds on others declares this through input ports.

The scenario

You work for an e-commerce company. In Part A, you own the Orders data: two PostgreSQL tables, orders and line_items. You put them under contract, release a breaking change as a new version, and describe the data product.

In Part B, you switch sides. The purchasing team wants to know how often each SKU sells per year, to negotiate with suppliers. You design a consumer-aligned data product, SKU Sales, on top of Orders (contract first) and implement it as a SQL view.

In Part C, you automate everything in your own GitHub fork: every push tests all contracts, and every pull request is checked for breaking changes. Part D is optional: you publish everything to a data product platform and link your contracts to business concepts.

The tools

All tools are open source and run locally:

• Data Contract CLI (datacontract): create, edit, lint, test, and compare data contracts
• Data Product CLI (dataproduct): create and lint ODPS data products
• Data Contract Editor: a visual editor, opened in your browser by datacontract edit
• PostgreSQL in Docker: the database with the sample data
• Entropy Data CLI (entropy-data): only for the optional Part D

How this tutorial works

Each exercise is a sequence of steps. Mark a step as done when you finish it. Done steps collapse, and your progress is saved in this browser. Commands have a copy button. Where instructions differ between macOS/Linux and Windows, switch tabs (your choice is remembered).

Stuck? Most exercises have a Show solution button. Try it yourself first.

Prerequisites: basic YAML and SQL. Plan about 5–6 hours for Parts A–C, plus about an hour for the optional Part D. You don't need to do it in one sitting.

Ready? Let's set up your environment.