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 toRules — the quality conditions that must be metSeverity — 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.csvExact file match customers_*.csvAny file starting with customers_ public.*Any table in the public schema *.parquetAll 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 < toke n > { "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 criticalBlocks downstream use. Immediate action required. warningQuality degradation detected. Should be addressed. infoNotable 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 < toke n >
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 tabEmail — if email alerts are enabled in settingsWebhooks — Slack or Microsoft Teams via webhook configurationPush 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 < toke n >
Update a contract PATCH /api/v1/contracts/{contract_id} Content-Type: application/json Authorization: Bearer < toke n > { "enabled" : false }
Add a rule to an existing contract POST /api/v1/contracts/{contract_id}/rules Content-Type: application/json Authorization: Bearer < toke n > { "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 < toke n >
Contract management endpoints require admin role. Viewing contracts and violations is available to all authenticated org members.
Next steps
AI readiness See how contract compliance affects readiness scoring
Classification Understand how columns are classified for targeted rules
