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

# Data contracts

> Define quality expectations for your data with enforceable contracts that are checked on every scan.

## Overview

Data contracts are SLAs for your data. You define the rules — a column must not exceed 5% nulls, values must stay within a range, no PII allowed — and ORCA checks them automatically every time a file is scanned. When a contract is violated, you get an alert.

Contracts are defined once and enforced continuously. They catch regressions before they reach production.

## Creating a contract

A contract consists of:

* **Name** — a descriptive label (e.g. "Customer data quality")
* **Target** — which files or tables the contract applies to
* **Rules** — the quality conditions that must be met
* **Severity** — how violations are prioritized

### Target matching

Contracts match files and tables using the `target_pattern` field. This supports exact names and glob patterns:

| Pattern           | Matches                             |
| ----------------- | ----------------------------------- |
| `customers.csv`   | Exact file match                    |
| `customers_*.csv` | Any file starting with `customers_` |
| `public.*`        | Any table in the `public` schema    |
| `*.parquet`       | All Parquet files                   |

### In the web app

Navigate to **Contracts** in the sidebar, click **Create Contract**, and configure the target pattern, rules, and severity levels using the form.

### Via the API

```bash theme={null}
POST /api/v1/contracts
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "Customer data SLA",
  "description": "Quality requirements for customer datasets",
  "target_type": "file",
  "target_pattern": "customers_*.csv",
  "enabled": true,
  "rules": [
    {
      "column_name": "email",
      "rule_type": "not_null",
      "config": {"max_null_rate": 0.02},
      "severity": "critical"
    },
    {
      "column_name": "revenue",
      "rule_type": "min_value",
      "config": {"min": 0},
      "severity": "warning"
    }
  ]
}
```

## Rule types

ORCA supports 10 rule types covering nulls, uniqueness, value ranges, format compliance, and data sensitivity.

### Column-level rules

| Rule type        | Config                         | What it checks                                             |
| ---------------- | ------------------------------ | ---------------------------------------------------------- |
| `not_null`       | `{"max_null_rate": 0.05}`      | Null rate must stay below threshold (0.0 to 1.0)           |
| `unique`         | `{}`                           | Column must have no duplicate values                       |
| `min_value`      | `{"min": 0}`                   | Minimum numeric value must be at or above threshold        |
| `max_value`      | `{"max": 1000000}`             | Maximum numeric value must be at or below threshold        |
| `format_match`   | `{"max_violation_rate": 0.05}` | Format violation rate must stay below threshold            |
| `regex_match`    | `{}`                           | Values must match expected format patterns                 |
| `allowed_values` | `{}`                           | Values must be from expected set (flags unexpected values) |
| `no_pii`         | `{}`                           | Column must not contain detected PII/GDPR-sensitive data   |

### Table-level rules

| Rule type       | Config              | What it checks                    |
| --------------- | ------------------- | --------------------------------- |
| `row_count_min` | `{"min": 1000}`     | File must contain at least N rows |
| `row_count_max` | `{"max": 10000000}` | File must not exceed N rows       |

Table-level rules do not require a `column_name`.

## Severity levels

Each rule has a severity that determines how violations are prioritized:

| Severity   | Meaning                                            |
| ---------- | -------------------------------------------------- |
| `critical` | Blocks downstream use. Immediate action required.  |
| `warning`  | Quality degradation detected. Should be addressed. |
| `info`     | Notable observation. No immediate action needed.   |

## Violation detection

Contracts are evaluated automatically after every scan completes. The evaluation process:

1. ORCA finds all enabled contracts for the organisation
2. Each contract's `target_pattern` is matched against the scanned filename
3. Every rule in matching contracts is checked against the quality results
4. Violations are recorded with full detail (expected vs. actual values)

Contract evaluation never blocks job completion — if evaluation fails, the error is logged but results are still delivered.

## Violation history

Every violation is stored with:

* The contract and rule that was violated
* The job and file that triggered it
* A detail object with expected vs. actual values
* The detection timestamp

### Viewing violations

In the web app, navigate to a contract to see its violation history. The 7-day violation count is shown on the contract list view.

### Via the API

```bash theme={null}
GET /api/v1/contracts/{contract_id}/violations
Authorization: Bearer <token>
```

Response:

```json theme={null}
{
  "data": [
    {
      "id": "uuid",
      "contract_id": "uuid",
      "rule_id": "uuid",
      "job_id": "uuid",
      "file_id": "uuid",
      "violation_detail": {
        "column": "email",
        "null_rate": 0.08,
        "threshold": 0.02
      },
      "detected_at": "2026-03-30T14:22:00Z"
    }
  ]
}
```

## Alerts on violations

When a contract violation is detected, ORCA creates an alert automatically. Alerts appear in the Alerts page and can be delivered via:

* **In-app notifications** — visible in the alerts tab
* **Email** — if email alerts are enabled in settings
* **Webhooks** — Slack or Microsoft Teams via webhook configuration
* **Push notifications** — on the mobile app (if push tokens are registered)

Critical-severity violations are highlighted in the dashboard summary.

## Managing contracts

### List contracts

```bash theme={null}
GET /api/v1/contracts
Authorization: Bearer <token>
```

### Update a contract

```bash theme={null}
PATCH /api/v1/contracts/{contract_id}
Content-Type: application/json
Authorization: Bearer <token>

{
  "enabled": false
}
```

### Add a rule to an existing contract

```bash theme={null}
POST /api/v1/contracts/{contract_id}/rules
Content-Type: application/json
Authorization: Bearer <token>

{
  "column_name": "phone",
  "rule_type": "not_null",
  "config": {"max_null_rate": 0.01},
  "severity": "warning"
}
```

### Delete a contract

```bash theme={null}
DELETE /api/v1/contracts/{contract_id}
Authorization: Bearer <token>
```

<Note>
  Contract management endpoints require admin role. Viewing contracts and violations is available to all authenticated org members.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="AI readiness" icon="chart-bar" href="/ai-readiness">
    See how contract compliance affects readiness scoring
  </Card>

  <Card title="Classification" icon="tags" href="/classification">
    Understand how columns are classified for targeted rules
  </Card>
</CardGroup>