dbt_contracts

A lightweight data contract control plane for multi-repository dbt ecosystems.

dbt model contracts validate what a model publishes internally, but in a multi-repository data-product ecosystem, producers also need to know whether proposed interface changes violate downstream consumer expectations without cloning or rebuilding downstream repositories in CI.

dbt_contracts provides:

• Canonical Data Contracts: Infrastructure-independent contract models with column schemas, types, nullability, and provenance.
• dbt Artifact Ingestion: Automatic extraction of public data models from dbt manifest.json.
• Central Contract Registry: SQLite-based (and extensible) registry storing immutable contract history and consumer declarations.
• Explicit Consumer Expectations: Downstream teams declare version ranges and required columns in simple YAML.
• SemVer Compatibility Engine: Deterministic classification of changes as PATCH, MINOR, MAJOR, or UNKNOWN.
• Consumer Impact Analysis: Identify which specific consumers and models will break when an interface changes.
• CI PR Gates: Producer CI runs dbt-contracts check with standardized exit codes (0 = valid, 1 = breaking gate failure, 2 = error).
• Organization-Scale Discovery: Scan Azure DevOps organizations to discover dbt projects and consumer contracts without cloning.

---

Architecture

dbt artifacts / repository metadata
              |
              v
      Discovery & Ingestion
              |
              v
    Canonical Contract Model
              |
      +-------+---------+
      |                 |
      v                 v
Contract Registry   Compatibility Engine
      |                 |
      +--------+--------+
               |
               v
        Consumer Impact
               |
               v
            CI Gate

---

Installation

pip install dbt-data-contracts

For development:

git clone https://github.com/your-org/dbt_contracts.git
cd dbt_contracts
python -m venv .venv
source .venv/bin/activate  # Or .venv\Scripts\Activate.ps1 on Windows
pip install -e ".[dev]"

---

Quickstart & CLI Usage

1. Ingest contracts from a dbt manifest

Inspect public contracts discovered in a dbt manifest:

dbt-contracts ingest --manifest target/manifest.json

2. Publish a contract version to the registry

Publish contracts for public dbt models (e.g. 1.0.0):

dbt-contracts publish \
  --manifest target/manifest.json \
  --version 1.0.0 \
  --registry .contracts.db

3. Register a downstream consumer expectation

Downstream consumers define data-contract-consumers.yml:

consumer: finance

dependencies:
  - product: orders
    model: fct_orders
    version: "^1.0.0"
    expectations:
      columns:
        order_id:
          data_type: bigint
          required: true
        amount:
          data_type: numeric
          required: true

Register the expectation in the central registry:

dbt-contracts consumer register \
  --file data-contract-consumers.yml \
  --registry .contracts.db

4. Check proposed changes in Producer CI

In producer pull request pipelines, test proposed contracts against published contracts and registered consumers:

dbt-contracts check \
  --manifest target/manifest.json \
  --proposed-version 1.1.0 \
  --registry .contracts.db

If a breaking change is detected (e.g., removing amount while finance requires it), the command outputs a detailed impact report and exits with code 1:

BREAKING CHANGE DETECTED: orders.fct_orders

Proposed: 1.1.0 (Current: 1.0.0)
Severity: MAJOR

Breaking changes:
  - Column 'amount' was removed

Affected consumers:
  - finance (expects 'amount: numeric', pinned to ^1.0.0)

SemVer Validation:
  FAIL: Breaking changes require a MAJOR version bump (expected >= 2.0.0).

If the proposed version is updated to 2.0.0:

dbt-contracts check \
  --manifest target/manifest.json \
  --proposed-version 2.0.0 \
  --registry .contracts.db

The check passes with exit code 0, confirming that 1.0.0 remains intact for existing consumers while 2.0.0 introduces the new breaking contract.

---

Development & Validation

Run all checks:

pytest
ruff check .
ruff format --check .
mypy src tests

Or run the dev check script:

./scripts/dev-check.sh

---

License

MIT License. See LICENSE for details.