> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/build/stage-2-productize/define-the-contract.md).

# Define the contract

The contract is the set of guarantees your data product makes about its data. Defining it is how you ensure that bad data never reaches downstream consumers: dashboards, APIs, or other data products that depend on yours.

***

## Three layers of the contract

| Tool                                                                                 | How it runs                             |     Blocks execution?     | Best for                                                     |
| ------------------------------------------------------------------------------------ | --------------------------------------- | :-----------------------: | ------------------------------------------------------------ |
| [Data quality checks](/build/stage-2-productize/define-the-contract/data-quality.md) | Automatically with models, or on-demand |             No            | Trend monitoring, anomaly detection, non-critical validation |
| [Assertions](/build/stage-2-productize/define-the-contract/assertions.md)            | Automatically at every materialization  |  Yes (stops the plan/run) | Critical business rules that must hold for every run         |
| [Tests](/build/stage-2-productize/define-the-contract/tests.md)                      | Manually, with `vulcan test`            | Yes (aborts the test run) | Verifying model logic during development against mock data   |

Use all 3 together for a complete contract:

```
DQ checks    --> monitor over time (watch for drift, anomalies, missing rows)
Assertions   --> enforce at execution time (block bad data from reaching production)
Tests        --> verify logic during development (mock data, no warehouse access needed)
```

***

## What orders-analytics uses

`orders-analytics` applies all four layers across its bronze, silver, and gold models:

| Layer                                    | What it checks                                                                                                                                                                                                                                                                                          |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **DQ rule packs** (in `dq/`)             | Seven DQ files covering row counts, null rates, value validity (e.g. `shipment_rate` must be between 0 and 1), and cross-table referential integrity across the bronze layer.                                                                                                                           |
| **Inline assertions** (in `MODEL` block) | Every model has `not_null`, `unique_values`, `accepted_values`, or `forall` assertions on its grain and key columns.                                                                                                                                                                                    |
| **Custom SQL assertions** (in `audits/`) | Three blocking assertions: `daily_sales_metric_consistency` checks that derived metrics are internally consistent, `rfm_score_consistency` validates that RFM scores and segment labels match, and `order_status_lookup_consistency` ensures every status in `bronze.orders` exists in the lookup seed. |
| **Unit tests** (in `tests/`)             | Two YAML tests: `test_fct_daily_sales_excludes_cancelled_orders` verifies that the revenue filter works correctly using mock data, and `test_rfm_customer_segmentation_champion` verifies that a high-value customer gets the Champions segment.                                                        |

***

## Where each lives in the project

```
orders-analytics/
├── tests/
│   ├── test_fct_daily_sales.yaml            # Unit test: cancelled orders excluded
│   └── test_rfm_customer_segmentation.yaml  # Unit test: champion segment logic
├── audits/
│   ├── daily_sales_metric_consistency.sql   # Blocking assertion: derived metrics
│   ├── rfm_score_consistency.sql            # Blocking assertion: RFM scores valid
│   └── order_status_lookup_consistency.sql  # Blocking assertion: referential integrity
└── dq/
    ├── fct_daily_sales.yml
    ├── fct_weekly_sales.yml
    ├── dim_customer_profile.yml
    ├── dim_product_profile.yml
    ├── rfm_customer_segmentation.yml
    ├── sales_funnel_analysis.yml
    └── referential_integrity.yml
```

Inline assertions live directly inside each model's `MODEL` block, not in separate files.

***

## Recommended approach

1. **During development**: Write tests against mock data to verify your SQL logic works the way you expect.
2. **At build time**: Add inline `assertions` to every model for critical integrity rules (`not_null`, `unique_values` on grain columns, `accepted_values` on status columns).
3. **For complex cross-model checks**: Add a SQL assertion file in `audits/` and attach it to the relevant model.
4. **At monitoring time**: Add a `kind: dq` rule pack for each important model to watch for row count drops, null rates, and value range violations after deployment.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/build/stage-2-productize/define-the-contract.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.