Healthcare Data Contracts: How to Enforce Schema Standards Across Teams

Introduction

A claims processing team changes service_date from DATE to VARCHAR to accommodate a legacy source system. The change passes code review, deploys on Friday, and breaks the HEDIS measure pipeline on Monday because the downstream team was casting it as a date. The HEDIS team finds out when their monthly run fails. The claims team finds out when the HEDIS team opens a ticket.

This scenario happens in every healthcare data organization without data contracts. A data contract is a formal agreement between the team that produces a dataset and the teams that consume it — specifying the schema, quality rules, latency SLAs, and ownership model. It is checked into version control, versioned alongside the schema, and enforced at deployment time.

In healthcare, where schema changes in one domain cascade into claims adjudication, risk adjustment submissions, and quality reporting pipelines, data contracts are not a governance formality. They are a reliability mechanism.

📊

Free Tool

Calculate RAF scores with our free HCC Calculator →

---

What a Healthcare Data Contract Contains

A data contract has five components:

1. Schema definition — the authoritative DDL for the dataset, including column names, data types, nullability, and constraints. This is the promise the producer makes to consumers: the data will always have this shape.

2. Quality SLAs — measurable rules the data must satisfy before it is considered production-ready. Row count minimums, null rate thresholds for critical columns, referential integrity checks, and domain-specific rules like "claim_paid_amount must be >= 0" or "npi_id must pass Luhn checksum."

3. Latency SLA — when the data will be available. For claims, that might be "all claims with service dates in the prior month will be present by the 5th of the following month." For eligibility, it might be "member records are refreshed daily by 6am ET."

4. Ownership — the team responsible for producing the data, the escalation path for quality issues, and the review process for schema changes.

5. Versioning and change policy — how schema changes are communicated, what constitutes a breaking change, and what notice period consumers receive before a breaking change deploys.

---

Defining Breaking vs. Non-Breaking Changes

The most important concept in a data contract is the distinction between breaking and non-breaking schema changes. Breaking changes require consumer notification and a migration window. Non-breaking changes can deploy without a deprecation process.

In healthcare data warehouses, the most dangerous breaking changes are column renames and type changes because they fail silently in SQL — a renamed column does not throw an error in a SELECT *, it just disappears from the output.

---

Data Contract Format

Data contracts work best as YAML files checked into the same repository as the DDL they describe. A minimal format:

# contracts/fct_claims.yaml
contract:
  name: fct_claims
  version: 2.1.0
  owner: claims-engineering@example.com
  consumers:
    - hedis-quality-team
    - risk-adjustment-team
    - finance-reporting-team

schema:
  columns:
    - name: claim_key
      type: BIGINT
      nullable: false
      description: Surrogate primary key

    - name: member_id
      type: VARCHAR(50)
      nullable: false
      description: Member identifier, joins to dim_member

    - name: service_date
      type: DATE
      nullable: false
      description: Date of service. Use this column for all date-range filters.

    - name: paid_amount
      type: DECIMAL(12,2)
      nullable: false
      description: Amount paid by the plan. Always >= 0.

    - name: primary_diagnosis_code
      type: VARCHAR(10)
      nullable: true
      description: [ICD-10](/terms/icd-10)-CM diagnosis code. Null for non-clinical claim types.

quality_rules:
  - rule: row_count_minimum
    threshold: 50000
    description: At least 50k claim rows expected per monthly load

  - rule: null_rate_maximum
    column: member_id
    threshold: 0.0
    description: member_id must never be null

  - rule: null_rate_maximum
    column: service_date
    threshold: 0.0
    description: service_date must never be null

  - rule: value_range
    column: paid_amount
    min: 0
    description: paid_amount must be non-negative

  - rule: referential_integrity
    column: member_id
    references: dim_member.member_id
    description: All member_ids must exist in dim_member

latency_sla:
  description: Claims with prior-month service dates available by 5th of current month
  schedule: "0 6 5 * *"

change_policy:
  breaking_change_notice_days: 14
  deprecation_process: notify consumers in #data-contracts Slack channel + email

---

Enforcing Contracts in CI/CD

A data contract in a YAML file that no one reads is not a contract — it is documentation. Enforcement happens when the CI/CD pipeline validates proposed schema changes against the contract before they merge.

Schema Diff Check

📐

Free Tool

Compare these two schemas instantly →

# In your CI pipeline: compare proposed DDL against contract schema
# Fail the build if a breaking change is detected without a version bump

python contract_validator.py   --contract contracts/fct_claims.yaml   --proposed-ddl migrations/V042__alter_fct_claims.sql   --check-breaking

A contract validator script reads the proposed DDL migration, extracts the column-level changes (renames, type changes, removals), and compares against the contract's defined schema. If breaking changes are found and the contract version has not been bumped, the pipeline fails.

Quality Rule Execution

-- Run quality rules from the contract after each load
-- This example runs the null rate check for member_id

SELECT
    'member_id_null_check'          AS rule_name,
    COUNT(*)                        AS total_rows,
    COUNT(CASE WHEN member_id IS NULL THEN 1 END)
                                    AS null_count,
    ROUND(
        100.0 * COUNT(CASE WHEN member_id IS NULL THEN 1 END) / NULLIF(COUNT(*), 0),
        4
    )                               AS null_rate_pct,
    CASE
        WHEN COUNT(CASE WHEN member_id IS NULL THEN 1 END) = 0 THEN 'PASS'
        ELSE 'FAIL'
    END                             AS result
FROM fct_claims
WHERE service_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '1 month');

Run all contract quality rules after each pipeline load. Log results to a tbl_data_quality_results table. Alert the owning team if any rule fails.

---

The Consumer Registration Pattern

One of the most valuable parts of a data contract is the consumers list. When every downstream team registers as a consumer of a dataset, the producing team knows who to notify before making a change — and consumers know where to look when something breaks.

In practice, consumer registration works like this:

1. A new team wants to build on fct_claims — they add themselves to consumers in the contract YAML and open a PR
2. The owning team reviews and merges — now the new team is on the notification list
3. Any future breaking change requires the owning team to get sign-off from all registered consumers before merging

Without this pattern, the claims engineering team does not know the risk adjustment team is joining on primary_diagnosis_code until the join breaks.

---

Version Semantics for Healthcare Data Contracts

Borrow semantic versioning from software:

• MAJOR version bump (1.x.x → 2.0.0): breaking schema change — column removed, renamed, or type-changed
• MINOR version bump (x.1.x → x.2.0): additive change — new nullable column, new table, expanded VARCHAR
• PATCH version bump (x.x.1 → x.x.2): non-schema change — quality rule update, description edit, latency SLA change

Consumers subscribe to a MAJOR version. When a new MAJOR version is released, consumers have the notice period (typically 14-30 days in healthcare) to migrate. After the notice period, the old MAJOR version is deprecated and eventually retired.

---

Data Contracts in a Healthcare Data Mesh

In a healthcare data mesh architecture — where payer, clinical, and pharmacy domains own their data products independently — data contracts are the interface layer between domains. The claims domain produces fct_claims under a contract. The risk adjustment domain consumes it. The quality measurement domain consumes it. Neither consumer team needs to know how claims data is produced internally — they only need the contract to guarantee the interface.

This separation of concerns is particularly important in healthcare because the same source data (claims) feeds multiple regulatory reporting workflows (HEDIS, RADV, CMS Encounter Data). Each reporting workflow needs a stable interface it can rely on, independent of upstream pipeline changes.

---

Frequently Asked Questions

Do data contracts work for teams using dbt?

Yes — dbt's schema.yml is a natural home for contract-adjacent definitions. Tests in schema.yml implement quality rules. The description fields document the schema. The gap dbt does not fill is the consumer registration, change policy, and latency SLA — those belong in a separate contract file that references the dbt model.

How do we handle contracts for tables that change frequently during development?

Mark contracts as status: draft until the table reaches production stability. Draft contracts have no formal consumer notification requirements — they signal "this schema is not stable yet." Promote to status: stable when the table is production-ready and downstream teams start building on it.

What tooling enforces data contracts at scale?

Open standards like OpenLineage and tools like Soda Core, Great Expectations, and Monte Carlo implement the quality rule enforcement layer. For schema change detection, tools like sqlfluff and custom DDL diff scripts handle the CI/CD integration. The contract YAML format itself is not yet standardized — teams use their own schemas or adopt emerging standards like the Data Contract Specification (datacontract.com).

---

Operationalizing Data Contracts with mdatool

For healthcare data teams building contract-enforced pipelines, mdatool provides the tooling to validate both schema compliance and naming standards at every stage. The mdatool Schema Diff detects breaking changes between DDL versions — input two CREATE TABLE scripts and get a precise diff of column additions, removals, type changes, and constraint modifications, exactly what a contract validator needs to flag breaking changes in CI. The mdatool Naming Auditor ensures schema changes comply with your naming conventions before they are committed to the contract — preventing a version 1.0.0 contract that already has inconsistent column names. The mdatool SQL Linter catches queries in consumer pipelines that will break silently when a column is renamed — SELECT star and implicit column references that bypass the contract's schema guarantee. The mdatool DDL Converter translates contract-defined schemas across warehouse dialects when a consumer team runs a different platform than the producer.