Data contracts

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

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:

ORCA finds all enabled contracts for the organisation
Each contract’s target_pattern is matched against the scanned filename
Every rule in matching contracts is checked against the quality results
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

GET /api/v1/contracts/{contract_id}/violations
Authorization: Bearer <token>

Response:

{
  "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

GET /api/v1/contracts
Authorization: Bearer <token>

Update a contract

PATCH /api/v1/contracts/{contract_id}
Content-Type: application/json
Authorization: Bearer <token>

{
  "enabled": false
}

Add a rule to an existing contract

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

DELETE /api/v1/contracts/{contract_id}
Authorization: Bearer <token>

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

Getting started

Features

Administration

Integrations

Security & compliance

Developer Tools

Methodology

Overview

Creating a contract

Target matching

In the web app

Via the API

Rule types

Column-level rules

Table-level rules

Severity levels

Violation detection

Violation history

Viewing violations

Via the API

Alerts on violations

Managing contracts

List contracts

Update a contract

Add a rule to an existing contract

Delete a contract

Next steps

AI readiness

Classification

​Overview

​Creating a contract

​Target matching

​In the web app

​Via the API

​Rule types

​Column-level rules

​Table-level rules

​Severity levels

​Violation detection

​Violation history

​Viewing violations

​Via the API

​Alerts on violations

​Managing contracts

​List contracts

​Update a contract

​Add a rule to an existing contract

​Delete a contract

​Next steps

AI readiness

Classification

Overview

Creating a contract

Target matching

In the web app

Via the API

Rule types

Column-level rules

Table-level rules

Severity levels

Violation detection

Violation history

Viewing violations

Via the API

Alerts on violations

Managing contracts

List contracts

Update a contract

Add a rule to an existing contract

Delete a contract

Next steps