Skip to content
croz-ltdPublic

About

An open-source Python framework that turns Git-versioned ODCS data contracts into enforced, engine-agnostic agreements between data producers and consumers, notifying the right owners directly in Microsoft Teams when a contract is breached.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

Servanda

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

Features

  • ODCS v3.1.0 compliant contract parsing
  • Multiple data sources: Postgres, S3, Db2, Oracle
  • Rule types: library (declarative metrics) and sql, plus schema_conformance checks 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)

Project structure

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.

Installation

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.

Usage

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 json

One maintainer cycle:

dcm plan --config dcm.yaml          # dry run — writes nothing
dcm sync --once --config dcm.yaml   # writes the manifest and state

Full CLI: docs/reference/cli.md.

Contract example

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: 0

Note 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.

Data sources

Type Status Driver
postgres Implemented psycopg2
s3 Implemented boto3 + pandas
db2 Implemented ibm_db
oracle Implemented oracledb

Notification channels

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.

Rule types

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.

Development

pytest
ruff check .
ruff format .
mypy contract_common contract_enforcer contract_maintainer

See docs/developer/howto/ for adding a source, rule provider, notifier, git host, or scheduler, and docs/developer/testing.md for the testing conventions.

Architecture in one paragraph

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/.

License

Copyright 2026 CROZ d.o.o. Licensed under the Apache License, Version 2.0; see NOTICE.

About

An open-source Python framework that turns Git-versioned ODCS data contracts into enforced, engine-agnostic agreements between data producers and consumers, notifying the right owners directly in Microsoft Teams when a contract is breached.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages