Skip to main content

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:

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

  1. Open the saved diagram the contract describes.
  2. In the top bar, click Contract, the page with the AI star in its middle, just left of Generate Model.
Contract works on the diagram that is open, and only once that diagram is saved: on a diagram that was never saved its tooltip reads Save the model first. Hover it otherwise to read Data model contract. A small dot on the button means the open diagram’s contract needs you, for example an unanswered question, a conflict or a table AI couldn’t write.

From Artifacts

  1. Open Artifacts in the project sidebar.
  2. Click New (+) at the top, then Data contract.
  3. 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.
  4. Click Start contract. When the model already has a contract the button reads Open contract instead.
If the project has no models, you see No models in this project yet. Create or generate a model first. If the list cannot be read, you see The models in this project could not be loaded. Check your connection and try again. with Try again. If a teammate starts the same contract at the same moment, you see Someone already started this contract. Showing it.

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.
  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. Click Generate contract in the status bar. AI reads saved schemas and the documents you include. Nothing is run against your warehouse.
The contract needs at least one source. Until you include one, Generate contract is unavailable and hovering it explains Add at least one source. If the chosen inputs cannot be used, the status bar says why. Generated models include AI-Generated Documentation among their reference documents. When you provide business context during model generation, that document starts with Business context and your original words. Generation notes are not separate contract inputs.

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.”
You can close the tab and come back: the draft keeps going, and Activity is still there for everyone who opens the contract.
  • 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.
Clicking Try again immediately replaces the failure with Writing and the table’s name. The card follows the actual work: finding sources, writing, and checking any fixes. It shows when the work started and offers Stop once the run is active. When writing finishes, the table’s questions and facts return. A refused start restores the failure card with its reason, so you can try again.
  • 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.
A table’s status reads Waiting, Writing, Question for you, To check (or a count such as “2 to check”), Updated, Looks right, Couldn’t be written, Stopped or Needs your choice. Updated marks a table an update changed that nobody has checked since. The ⋯ menu beside the contract name (More actions for the contract name) holds Download full YAML, Edit contract inputs and Discard draft.

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.
  1. 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.
  2. Answer any Questions at the top: see Answer a question.
  3. Read the facts. Each one is a row: its label, what it says, and one quiet line underneath.
  4. Change anything you disagree with: see Change a line.
  5. 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.
  6. Read the basis under a fact, or click its Ask AI button to understand why it was chosen.
  7. Click Looks right at the bottom of the sheet.
A table shows only the facts it has: 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.
Approval needs every table marked Looks right as it is now. Any later change to a table clears its check: an edit, an answer, a suggestion you accept, an update, or a teammate’s change. Check it again.

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.
  1. 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.
  2. Ask in Ask a follow-up… if you need more detail. If a follow-up changes the recommendation, a new recommendation follows the reply.
  3. 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.
  4. Click Answer when you are happy. Use this answer only selects an option; it does not submit it.
Advice is saved with the question. Click View advice to bring it back into view in Ask AI. Asking for advice leaves the contract and its Looks right checks unchanged. Once you answer, the advice stays in the conversation marked Answered; if AI asks a new question instead, the earlier advice is marked Earlier version. While the question is open, the fact it is about reads Waiting for your answer to AI’s question. If you would rather write that line yourself, click Change on it instead of answering. You see Applying your answer… while the table is rewritten from your answer: AI rewrites its other facts and summary with it, so they agree. The new lines read “Based on your answer”. If it fails, the reason shows under the question; try again.

Change a line

Use this when you know what a line should say.
  1. Point at the line and click Change. On a line AI wasn’t sure about, Change is always visible.
  2. 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.
  3. Click Save, or Cancel to leave it as it was. Escape also cancels and puts you back on Change.
If a change does not work with the model, nothing is saved and you see This change can’t be saved yet: followed by what to fix. Which tables a line reads and how their rows are matched cannot be edited here: the editor says To change which tables this reads or how their rows are matched, ask AI instead. A line you save shows your words with You changed this as soon as the editor closes. If someone else changes the line while your editor is open, the editor says Changed by someone else since you opened it. Click Show the new version to start again from theirs. Changing a line clears the table’s check, so mark the table Looks right again. An update will not overwrite your line silently. To get AI’s original wording back, open the line’s editor and click Revert to AI’s version. It only appears on lines that people have changed.

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.
  1. 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.
  2. Click the round Send button or press Enter. Shift+Enter adds a new line.
  3. 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.
While the table has an unanswered question, Help me decide is offered too: it points the box at that question and asks for advice if none is saved yet. For one line, click its Ask AI button, or open Change and choose Ask AI instead. The tag in the message box names the line. Why this? and Change this fill the box; on an unsure line they read Why wasn’t AI sure? and Suggest a better way. Click the tag’s close button to ask about the whole table again. The conversation scrolls inside the drawer and the message box stays at the bottom. While AI answers, the box says so and waits for that answer; you can still point it at another line and ask there. Hide details gives the sheet its space back and Show details brings it back.

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.yaml file; it is available here and on the overview’s menu. Opening a table or Overview takes you back.
If the YAML cannot load, click Try again. Copy says Copied only when it succeeds. If your browser blocks copying, download the document from See full YAML. The YAML is for reading. To change the contract, change the lines.

Approve the contract

  1. 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.
  2. Click Approve contract.
  3. 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.
  4. Under Before you approve you may see notes that do not stop you, such as a selected source that nothing uses.
  5. 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.
If something still blocks approval, the window lists it under Approval needs a few things first: and Approve and save stays unavailable. Click Cancel, fix the items and try again. If a teammate changes the contract while the window is open, Approve and save saves nothing and you see Someone else changed this contract. Showing the latest version. The window stays open and lists what now blocks approval, for example DIM_Customer is not checked yet. when their change cleared that table’s check. You see Saved version 1.0.0 to Artifacts. with Open. The centre shows Contract approved and “Version 1.0.0 of the TPCH sales contract is saved in Artifacts.” The bar reads, for example, Approved as version 1.0.0 by Sam Lee on 21 Oct 2026. Three next steps follow:
  • 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.
Click Overview in the left list to go back to the tables. The YAML tab shows the approved contract straight away. The contract is saved under contracts/ in Artifacts, for example 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

  1. Click Overview in the left list, then open the ⋯ menu beside the contract name and choose Discard draft.
  2. In Discard this draft?, click Discard draft.
You see Draft discarded. The draft, its answers and changes are deleted. Approved versions in Artifacts stay.

Work with teammates

More than one person can review the same contract. Changes show up without a refresh. Lines show who changed them (Changed by a name) and tables show who checked them (Checked by a name, or Checked by someone else). Because a teammate’s change clears that table’s check, a table you marked can come back needing a look. If someone else changed what you were working on, you see Someone else changed this line. Showing the latest version. or Someone else changed this contract. Showing the latest version.

What’s next