What you’re building
A data contract is the build spec for a model. For every table it sets out the source mappings, transformation rules and load behaviour. Hand it to an AI coding agent, such as Claude Code, Cursor or Codex, or to AI in Snowflake or Databricks, to build the pipeline that turns your source data into the model. You pick a model and the sources it loads from. AI writes the contract for every table and narrates what it is doing while it works. You then check the contract one table at a time: answer the few questions AI has, change anything you disagree with and mark each table Looks right. When every table is checked, you approve. Approval saves the contract to Artifacts as a standard ODCS YAML file that a coding agent can build the pipeline from. Related guides:- Update a data contract when the model or its sources change after approval.
- Set contract defaults to give AI your house rules once for the whole project.
- Save and certify a version for the versions every approval adds.
Before you start
- The model is a saved diagram with at least one table.
- The project has source tables to load from. Import them first if it does not: see Reverse engineer (import).
Start a contract
You can start from the model or from Artifacts. Both open the same contract tab. A model has one contract draft at a time, so if one already exists you are taken to it.From the model
- Open the saved diagram the contract describes.
- In the top bar, click Contract, the page with the AI star in its middle, just left of Generate Model.
From Artifacts
- Open Artifacts in the project sidebar.
- Click New (+) at the top, then Data contract.
- In New data contract, find the model with Search models and click it. Each row shows how many tables the model has and, once a contract exists, its state: Drafting, In review or Approved as 1.0.0.
- Click Start contract. When the model already has a contract the button reads Open contract instead.
Check the sources and generate the contract
A new contract opens on Create the data contract for and the model’s name. Three steps show what you do here: Confirm inputs, Generate, and Review and approve. A line under them says what comes next: hand the approved contract to Claude Code, Cursor, Codex or your warehouse’s AI to build the pipeline. Nothing is written until you click Generate contract in the status bar. On the left, Tables in this model lists each table, its kind and where its data comes from. Back to data model, at the foot of the list, opens the model’s diagram. It remains available while AI writes and during review and approval. Activity starts as a slim strip on the right; click its icon to open it. It opens by itself when AI starts writing.- In Source datasets, check how many tables have a source. A table counts when your model links it to a source you include, or the load generates it, such as a date table. Ready means every table is covered. Otherwise, AI looks for a source when it writes. The bar distinguishes saved links, generated tables and tables AI will match.
- Check the table chips, grouped by source model, or by schema for tables that come from no model. Each group shows how many of its tables are included, and each chip shows a table’s name and column count. Click a chip, or press Space on it, to include or leave out that table. Click a source model’s heading to include or leave out all its tables; when only some are included, its box shows a dash. The count and the source text beside each model table update with your choices.
- To add a source, click Add source, type in Search source tables and diagrams and press Enter. Pick a result to include it. Escape closes the search and returns to Add source. When no source is included, you see Add the source tables this model is loaded from.
- In Reference documents, switch on the documents that explain the model, such as column mappings or business notes. Each row shows the name and size, for example Markdown · 13 KB. AI reads these to understand intent; no data is loaded from them. Click Add, type a name and press Enter to find another document. With none listed, you see No documents yet. Add one that explains the model, such as column mappings or business notes.
- Optionally, click Instructions for AI, below the two cards, and click Add to open it. Write anything the contract must follow that the model and documents do not say, for example which source to trust when two disagree on a customer’s address. The counter updates as you type, up to 5,000 characters. Press Enter or leave the field to keep your text. Hide folds it again; once it has text it opens with the page.
- Read Project defaults: and the rules that follow. Click Edit to change them for every contract in the project. If none are set, click Set defaults beside No project defaults set. See Set contract defaults.
- Click Generate contract in the status bar. AI reads saved schemas and the documents you include. Nothing is run against your warehouse.
When the contract cannot start
In these cases the bar above the panels names what the model needs first, for example Import the source tables first., and Activity stays empty until a contract can start.
Watch AI write the contract
The centre changes to Writing your contract, with a progress bar that reads, for example, “3 of 7 tables done”. The bar above the panels says what you can do meanwhile, AI is working through your tables. Open any table as soon as it is done., and holds Stop. When you open a table, the bar reads Writing your contract. and keeps Stop.- Left list. Under each table’s name you see where it is: Waiting, Finding sources, Writing or Checking. A table opens as soon as it is done, so you can start reading it while the rest keep writing.
- Activity. The right panel opens on Activity. Live and the time since it Started show at the top. Below, newest first, each line says what AI just did, with the time to the second and an icon for done, fixed, a question or a failure. The step AI is on now spins; once it moves on, the line turns grey. Under the feed: “Every line AI writes is checked against your model and sources before you see it.”
- Stop halts the run. Tables already written are kept, and the status bar then offers Resume, which writes only the tables that are not finished; hover it to see so. As soon as you click Resume or Retry, the bar shows the run under way with Stop.
- When a table fails, its status reads Couldn’t be written. Open it to see AI couldn’t write this table, the reason once for the whole table, and two buttons: Try again and Check the sources.
- Two contracts can be written at the same time in a project. A third shows Two contracts are already being written in this project. Try again when one finishes.
Find your way around
The contract tab is one slim status bar over three panels. The status bar always says the single next step and has at most two buttons. The wording comes from the contract itself, for example:- Left: the tables. The contract name, a line such as “4 of 7 tables checked” with a thin bar, Overview, then every table with a status icon, its name, its kind (Dimension, Fact or Table) and a number for how many things in it need a look.
- Centre: what you are looking at. The writing progress, the Overview, one table’s sheet or, after approval, the approved screen.
- Right: details. Three tabs: Activity, the open table’s YAML (named like a file, for example nation.yaml) and Ask AI. The icon at the top of the panel, Hide details, folds it into a thin strip, and Show details brings it back. The panel opens on Activity. Once you pick a tab it stays.
The overview
Click Overview in the left list. It shows:- The contract name and where it was written from, for example “Draft · written by AI from TPCH source”.
- The progress, for example “4 of 7 tables checked”, with a thin bar.
- When questions are open, a callout such as “AI has 1 question for you” with Answer, which takes you to the table that asks.
- What changed, after an update.
- Tables: one row per table with its name, its kind, one plain sentence about what it is and its status. Click a row to open its sheet.
Check a table
A table’s sheet reads like a short spec in plain English. Open it from the left list, from the Overview, or with Check next table in the status bar.- Under the table’s name, a line reads, for example, “Dimension · 13 columns · table 2 of 7”. Below it is a one-sentence summary of the table.
- Answer any Questions at the top: see Answer a question.
- Read the facts. Each one is a row: its label, what it says, and one quiet line underneath.
- Change anything you disagree with: see Change a line.
- Look through Columns. Each row shows the column name and where its value comes from in plain words, for example “CUSTOMER.C_NAME” or “Set by the load: a new number for each version”. A long table shows its first 50 columns: click Show and the number left, for example Show 12 more, to load more.
- Read the basis under a fact, or click its Ask AI button to understand why it was chosen.
- Click Looks right at the bottom of the sheet.
The quiet line under a fact is one of three things:
- What it rests on, for example “Based on where your model says the data comes from”, “Based on the keys in your model”, “Your house rule”, “Based on” a document’s name, “Based on your answer” or “AI’s choice”.
- AI wasn’t sure. followed by one sentence on why. AI flags a line only when it was unsure, so these are the lines to look at first. Change stays visible on them.
- Who last changed it: You changed this, Changed by a name or Changed by someone else.
Mark the table as right
Looks right signs off the whole table. The table shows as checked in the left list straight away, a little faded while the check is saved, and the next table that needs a look opens at once, or the Overview when none does. If the check cannot be saved, the table goes back to how it was, a message says why and you are taken back to that table, unless you already opened another one. A second click on Looks right that lands after you moved on does not check the next table. A checked table reads Checked by you under its summary. Previous goes back a table, and next to Looks right the sheet says where you will go next, for example Then DIM_Date. A table that already looks right shows Next table instead. Looks right is unavailable, and hovering it says why, while:- A question is open: Answer the question first.
- AI is updating a line: Wait for AI to finish updating this table.
- A line has a conflict after an update: Choose a version for each line that changed.
- The table failed or is still being written.
Answer a question
When AI cannot tell what a table needs, it asks instead of guessing. The question sits under Questions at the top of the table, with a short reason underneath. The status bar says how many are open, for example “AI has 1 question for you”, and its Answer button takes you to the table that asks.- If you want help comparing the options, click Help me decide. The Ask AI tab opens in the right drawer, and the box at the bottom names the question. AI reads the table, your model and your house rules, then explains its recommendation with reasons and short labels showing what supports them. Each option gets a sentence explaining what it means. When the facts cannot decide, It depends on explains what you still need to choose.
- Ask in Ask a follow-up… if you need more detail. If a follow-up changes the recommendation, a new recommendation follows the reply.
- Click Use this answer on the latest recommendation to select that option. The drawer stays open at the same place. You can also choose another option on the sheet. You can also pick Answer in your own words and type in Describe the answer in your own words.
- Click Answer when you are happy. Use this answer only selects an option; it does not submit it.
Change a line
Use this when you know what a line should say.- Point at the line and click Change. On a line AI wasn’t sure about, Change is always visible.
-
The editor opens right under the line. Change the fields. The choices depend on the line:
Every line also has In plain words, a description you can edit. When you pick another option, it changes to say what that option does, until you write your own. With Keep every version, it names the Versioned columns and follows them as you add or remove one. For a list of columns, click Add column and search with Search columns. Mark them deleted needs the column that says a row was deleted; until you pick one, the editor says so.
- Click Save, or Cancel to leave it as it was. Escape also cancels and puts you back on Change.
Ask AI about a table or line
Click Ask AI beside the table name to open the Ask AI tab in the right drawer. It holds one conversation for the table: everything you and AI said about the table, its lines and its questions, oldest at the top, each part under a label naming what it was about. Click a label to find that line or question on the sheet. The tag in the message box names where your next message goes; here it names the table. You can ask while the table has an unanswered question.- Type your message, for example “Why is it built this way?” or “Keep a history of address changes.” The suggestions fill the box for you without sending.
- Click the round Send button or press Enter. Shift+Enter adds a new line.
- Read the reply above the box. Answers explain the table and show what supports them. Go to the question, when offered, takes you to the open question the reply is about.
Review a suggested change
When your message asks for a change, the reply shows Writing the suggestions… while AI works. The proposals appear on the lines they affect, with Accept and Discard. Click a changed-line label in the reply to jump there. Accepting or discarding one suggestion from a table request settles that request’s suggestions together. Open questions stay open for you to answer. If nothing needs to change, the conversation says AI found nothing to change and gives the reason when one is available. If a request fails, its reason appears where you asked, with Try again. Conversations remain available when you reopen the table; asking for an explanation does not clear its Looks right check. A fact written or accepted by a person stays protected from a whole-table request. The result explains when that prevents a change. Activity also keeps the explanation and offers Go to Change when it can point to the protected fact.When asking is unavailable
The table explains why before you send. If AI could not write the table, use Try again at the top of the table first. While AI is updating it, wait for it to finish. Each conversation accepts up to 20 questions and shows a message when it reaches that limit.Ask AI about the whole contract
On the Overview, the Ask AI tab holds one conversation for the whole contract, and the tag in the message box reads Whole contract. Ask which tables still need you, how tables fit together or where they disagree. AI reads a short version of every table, so it can answer without you opening each one. Tables and lines it mentions are links: click one to open that table at the line. You can also ask for a change across tables, for example “Keep a history of changes on every table that needs it.” AI picks the tables the change reaches and sends each one its own request, as if you had asked on that table. The reply lists the tables with how each is going: Writing suggestions…, then how many suggestions there are to review, Nothing to change with AI’s reason underneath, or Didn’t finish, open it to try again. Click a table to review its suggestions on its lines with Accept and Discard. Each table’s request also appears in that table’s own conversation. A table AI can’t change right now is listed with the reason, for example AI is already updating it or AI hasn’t written it yet, and nothing is started on it. One change reaches at most 8 tables. If it would reach more, AI asks you to name the tables to start with or to narrow the request, and changes nothing.Read activity and YAML
- Activity keeps the history of what AI did, newest first. To understand a decision, read its basis line or click Ask AI on that fact.
- The YAML tab shows the open table’s section and is named after it, for example nation.yaml; on the overview it shows the contract header as header.yaml. Copy copies only the visible section. The table’s menu offers Open table YAML, which opens the panel at the top of that section.
- See full YAML under Overview opens the whole contract in the centre. Download full YAML saves the entire contract as a
.odcs.yamlfile; it is available here and on the overview’s menu. Opening a table or Overview takes you back.
Approve the contract
- Check every table. The progress line reads “7 of 7 tables checked” and the status bar reads, for example, “Ready to approve” with Approve contract. Until then Approve contract is unavailable, and hovering it says why.
- Click Approve contract.
- In the window titled Approve and the contract name, read what will be saved: This saves version 1.0.0 of the contract to Artifacts. with the reason it is that version, then 7 tables checked by you if you checked them all, or 5 checked by you and 2 by others when teammates checked some. When people changed lines, a line such as “3 lines changed by people” follows.
- Under Before you approve you may see notes that do not stop you, such as a selected source that nothing uses.
- Click Approve and save. While it saves, the button reads Saving version 1.0.0… and the window stays open until the version is saved: Cancel and the close button are hidden, and Escape or a click outside does nothing, because the save cannot be stopped once it starts.
- Hand it to a coding agent: click Download to save the contract file to build the pipeline from.
- Open in Artifacts: click Open in Artifacts to see this and earlier versions side by side.
- Stays in step with the model: when the model changes, the Contract button shows a dot and AI updates only what changed. See Update a data contract.
TPCH_sales_contract.odcs.yaml, and a version named Contract 1.0.0 is added to its history. See Save and certify a version for what you can do with versions.
An approved contract stays open for changes. Change a line and that table’s check is cleared, so check it again and approve again to save a new version.
When you open the saved file from Artifacts, a bar reads Saved from a data contract. Edits here are not carried back into the contract. Click Open contract to go back to the contract.
Discard a draft
- Click Overview in the left list, then open the ⋯ menu beside the contract name and choose Discard draft.
- In Discard this draft?, click Discard draft.