> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snaplabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Draft and approve a data contract

> Let AI write a contract that says where each table in a model gets its data, check it one table at a time, then approve it as a saved contract.

## 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](https://docs.snaplabs.ai/guides/update-a-data-contract.md) when the model or its sources change after approval.
* [Set contract defaults](https://docs.snaplabs.ai/guides/set-contract-defaults.md) to give AI your house rules once for the whole project.
* [Save and certify a version](https://docs.snaplabs.ai/guides/save-and-certify-a-version.md) 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)](https://docs.snaplabs.ai/guides/create-logical-physical-model.md#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](https://docs.snaplabs.ai/guides/set-contract-defaults.md).
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

| You see | What to do |
| - | - |
| **This model has no tables yet** | Click **Open the model**, add tables and save it. |
| **This model is too large for one contract** | Click **Open the model** and remove tables you do not need or split the model. The message gives the column count and the limit. |
| **No source tables in this project yet** | Click **Import source tables** and choose how to import them. |
| **This model's sources could not be loaded** | Check your connection and click **Try again**. |

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:

| The bar says | Button |
| - | - |
| AI has 1 question for you | **Answer** |
| 3 tables left to check | **Check next table** |
| Ready to approve | **Approve contract** |
| Writing your contract | **Stop** |
| TPCH sales changed since version 1.0.0 | **Update contract** |

* **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](https://docs.snaplabs.ai/guides/update-a-data-contract.md).
* **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](https://docs.snaplabs.ai/guides/update-a-data-contract.md) 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](#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](#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:

| Fact | What it tells you |
| - | - |
| **Built from** | Which source tables it is built from and how they are joined. |
| **Rows included** | Which rows are kept. Only shown when the table filters rows. |
| **If a row appears twice** | Which copy wins. Only shown when the table removes duplicates. |
| **One row is** | What a single row stands for. |
| **Kept up to date** | Whether a load rebuilds, adds or updates rows, and how changes are found. |
| **Changes over time** | Whether history is kept or changes overwrite. |
| **If a source row is deleted** | Whether the row is ignored, marked deleted or removed. |

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:

   | Line | Fields |
   | - | - |
   | **One row is** | **Identified by** |
   | **Built from** | **Join type** (**Only rows that match**, **Every row, matched where possible** or **Every row from both sides**) |
   | **Rows included** | **Columns it reads** |
   | **If a row appears twice** | **Duplicates share**, **Keep the row with** (**Highest first** or **Lowest first**) |
   | **Kept up to date** | **How it loads** (**Rebuild every run**, **Add new rows** or **Update and add rows**), **Matched on** (with **Update and add rows**), **Spot changed rows by**, **Also re-read rows changed in the last** number of **hours** or **days** |
   | **Changes over time** | **History** (**Overwrite changes** or **Keep every version**), **Versioned columns** (with **Keep every version**) |
   | **If a source row is deleted** | **Deleted source rows** (**Ignore them**, **Mark them deleted** or **Remove them**), **Marked in** (with **Mark them deleted**) |
   | A column | **Uses**, the columns it is derived from |

   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](https://docs.snaplabs.ai/guides/update-a-data-contract.md) 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](https://docs.snaplabs.ai/guides/update-a-data-contract.md).

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](https://docs.snaplabs.ai/guides/save-and-certify-a-version.md) 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

* [Update a data contract](https://docs.snaplabs.ai/guides/update-a-data-contract.md)
* [Set contract defaults](https://docs.snaplabs.ai/guides/set-contract-defaults.md)
* [Create an artifact](https://docs.snaplabs.ai/guides/create-artifact.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.