Pacta sunt servanda — agreements must be kept. Servanda keeps your data contracts.
Servanda is two cooperating components under one name:
- Servanda Enforcer (
dce,contract_enforcer) — the execution plane. Reads an ODCS contract, runs its checks against the data source, reports the result. - Servanda Maintainer (
dcm,contract_maintainer) — the control plane. Watches a git repo of contracts and schedules the enforcer in Airflow.
In more detail: a data contract enforcement engine that reads contracts written in the Open Data Contract Standard (ODCS), executes the quality and SLA checks declared in them, and reports results through configured notification channels — plus a maintainer that watches a git repository of contracts and schedules those checks in Airflow.
📖 Full documentation → · Architecture · ODCS reference · DEMO
- ODCS v3.1.0 compliant contract parsing
- Multiple data sources: Postgres, S3, Db2, Oracle
- Rule types:
library(declarative metrics) andsql, plusschema_conformancechecks derived automatically from the contract's own schema declarations - Multiple notification channels: Email (SMTP), Microsoft Teams (webhook)
- Push-down execution — run checks in the database when the source supports it
- Pull-mode fallback — local pandas evaluation when it doesn't
- Git-driven scheduling — contracts declare their own cron; the maintainer renders Airflow DAGs
- Referenced secrets — credentials named via
${ENV_VAR}, resolved at connect time - Pluggable execution — checks run in the Airflow worker, or in a Kubernetes pod with its own resource envelope (docs)
contract_common/ # driver-free shared foundation (validation, state, provenance)
contract_enforcer/ # execution plane — engine, providers, source & notifier adapters
contract_maintainer/ # control plane — sync cycle, schedule parsing, planner, adapters
deploy/ # delivery artifacts, never part of any distribution
airflow-bundle/ # what Airflow pulls: thin DAG shims + generated manifest
images/ # Dockerfiles for the Airflow image and the enforcer image
data_contract_examples/# example ODCS contracts (also used as test fixtures)
docs/ # all project documentation
tests/
Architecture in full: docs/architecture/overview.md.
python -m venv .venv
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
pip install -e ".[dev,postgres]"Drivers are optional extras — postgres, oracle, db2, s3, email, or all. A shop that never uses Oracle never needs an Oracle client. See docs/reference/configuration.md.
dce validate path/to/contract.odcs.yaml
dce run path/to/contract.odcs.yaml
dce run path/to/contract.odcs.yaml --dataset orders
dce run path/to/contract.odcs.yaml --rule row-count-check
dce run path/to/contract.odcs.yaml --output jsonOne maintainer cycle:
dcm plan --config dcm.yaml # dry run — writes nothing
dcm sync --once --config dcm.yaml # writes the manifest and stateFull CLI: docs/reference/cli.md.
apiVersion: v3.1.0
kind: DataContract
id: "urn:ddcd:contract:orders:v1"
name: Orders Data Contract
version: "1.0.0"
status: active
servers:
- server: production
type: postgres
host: ${POSTGRES_HOST}
port: 5432
database: ${POSTGRES_DATABASE}
username: ${POSTGRES_USERNAME}
password: ${POSTGRES_PASSWORD}
schema: public
schemas:
- name: orders
physicalType: table
quality:
- id: row-count-positive
type: sql
query: "SELECT COUNT(*) FROM {object}"
mustBeGreaterThan: 0
schedule: "0 6 * * *" # cron ⇒ id is required
properties:
- name: order_id
logicalType: integer
physicalType: INTEGER
primaryKey: true
required: true
- name: email
logicalType: string
quality:
- id: no-null-emails
type: library
metric: nullValues
mustBe: 0Note that operators are YAML keys, not fields — mustBeGreaterThan: 0, never operator: + threshold:. Quality rules live inside schemas and properties, never at the contract root. Working examples are in data_contract_examples/; the full syntax reference is docs/reference/odcs-contracts.md.
| Type | Status | Driver |
|---|---|---|
postgres |
Implemented | psycopg2 |
s3 |
Implemented | boto3 + pandas |
db2 |
Implemented | ibm_db |
oracle |
Implemented | oracledb |
Selected by tool on a contract's support entry.
| Type | Status | Description |
|---|---|---|
email |
Implemented | SMTP email with HTML report |
teams / ms_teams |
Implemented | Microsoft Teams webhook |
Enforcer runs notify through these. The maintainer does not — its quarantine and deletion notices currently only log.
type |
Status |
|---|---|
library |
Implemented |
sql |
Implemented |
schema_conformance |
Implemented (emitted automatically, not hand-authored) |
custom (Great Expectations) |
Implemented — pip install "servanda[ge]". Only engine: greatExpectations / ge; |
text |
Not implemented — should be inert, currently rejected by validation |
Great Expectations rules ship as a separate distribution (packages/enforcer-ge/) so GE's Python cap (<3.14) and 22 dependencies stay off the core. Reference: docs/reference/great-expectations.md.
Gaps, with what each would take: docs/developer/todo.md.
pytest
ruff check .
ruff format .
mypy contract_common contract_enforcer contract_maintainerSee docs/developer/howto/ for adding a source, rule provider, notifier, git host, or scheduler, and docs/developer/testing.md for the testing conventions.
Hexagonal — ports and adapters. The core is source-agnostic: it imports interfaces, not drivers. Adapters implement ports (DataSource, Notifier, StateStore, ContractRepository, SchedulerBackend); providers implement rule execution; registries map type strings to classes at runtime. The engine never knows which source or which kind of rule it is running — that is the property everything else is built to preserve. See docs/architecture/.
Copyright 2026 CROZ d.o.o. Licensed under the Apache License, Version 2.0; see NOTICE.