Data Contract Checker

Validate data contracts against configurable rules — with human-readable output.

📖 Full documentation: godatadriven.github.io/contract-checker

Data Contract Checker is an open source Python package for defining, enforcing, and maintaining validation rules across your data contracts. Define the best practices and naming conventions you care about once — required fields, naming patterns, accepted values — then enforce them consistently across a large number of contracts. Run the CLI and get clear pass/fail feedback on every contract in your repository.

This makes it practical to keep a large, growing set of data contracts consistent: instead of reviewing each contract by hand, you codify your team's conventions as checks and let the tool enforce them everywhere.

It supports the two major open data contract standards out of the box, with custom JSON Schema support for everything else.

---

Supported standards

Standard	Versions
DCS — Data Contract Specification	0.9.0 – 1.2.1
ODCS — Open Data Contract Standard	2.2.1 – 3.2.0
Custom JSON Schema	any

See the documentation for the full version-compatibility detail per standard.

---

Installation

pip install contract-checker

# or with uv
uv add contract-checker

Requires Python 3.11–3.15.

---

Quick start

1. Create a data-contract-checks.yml file in your project root:

data_contract_specification: dcs   # or "odcs" / "custom"

data_contracts_path:
  path: ./contracts/               # where your contracts live
  exclude_paths:
    - archive/**                   # optional glob filters

data_contract_checks:
  - attribute: info.title
    checks:
      - required: true
      - pattern: "^[A-Z]"          # title must start with a capital letter

  - attribute: info.version
    checks:
      - required: true
      - pattern: "^\\d+\\.\\d+\\.\\d+$"  # must be semver

  - attribute: models.*.fields.*.description
    checks:
      - required: true             # every field must have a description

  - attribute: servers.type
    checks:
      - accepted_values:
          - s3
          - gcs
          - azure_blob

2. Run the checker against your contracts:

contract-checker

To also show passing checks and fully passing contracts:

contract-checker --output-mode full

For a one-line-per-contract scoreboard use --output-mode summary, and for machine-readable output use --format json. --verbose / -v enables debug logging.

To validate a different location (or a single contract) ad hoc, override the configured path with --contract-path:

contract-checker --contract-path ./contracts/orders.yaml

To also validate each contract against its full JSON Schema (the built-in DCS/ODCS schema, or your custom one) — the equivalent of datacontract lint — enable linting. It's off by default:

contract-checker --lint

For the full config-file schema — path filtering, severity overrides, linting, and custom schemas — see the configuration guide.

---

Available checks

Check	YAML key	Description
Required	required: true	Field must exist and be non-null
Pattern	pattern: "^regex$"	Value must match a regular expression (for list attributes, every item must match)
Accepted values	accepted_values: [a, b]	Value must be one of the listed options
Min items	min_items: 2	List or mapping must contain at least N items; skipped if missing, fails if not a collection
Max items	max_items: 10	List or mapping must contain at most N items; skipped if missing, fails if not a collection
At least one	at_least_one: {unique: true}	At least one item in a collection must match the key-value condition (point attribute at the collection, e.g. models.*.fields)
Exactly one	exactly_one: {primaryKey: true}	Exactly one item in a collection must match the key-value condition, e.g. a single primary key per model

Only required checks whether a field exists: every other check skips an absent field, and every check fails a field that is present but null. See missing vs null values.

See the checks reference for full details and examples of each check type.

---

Key features

• Wildcard path support — apply checks across all models and fields with models.*.fields.*.unique
• Severity levels — --severity error (default) fails the run when checks fail; --severity warn prints the same report but always exits 0
• Contract filtering — include or exclude contracts with glob patterns (domain/**, **/draft_*.yaml); filtering by field value (e.g. only status: active contracts) is planned
• Schema validation (lint) — opt into full JSON Schema validation with --lint, against the built-in DCS/ODCS schema or your own custom schema (like datacontract lint)
• Custom JSON Schema — validate contracts against your own schema, on top of your configured checks
• Rich output — colour-coded pass/fail tables per contract plus a summary across all contracts, or JSON with --format json
• GitHub Actions annotations — failed checks are emitted as error annotations automatically when running in GitHub Actions
• Extensible — implement the Check abstract base class to add your own check types via the Python API

---

Configuration reference

The full configuration schema — including path filtering, severity overrides, and custom schema options — is documented at godatadriven.github.io/contract-checker.

---

Contributing

Bug reports, feature requests, and pull requests are all welcome. See CONTRIBUTING.md for dev setup, how to add a new check type, and the PR process.