Contracts

Contracts are the source of truth.

ContractForge separates data movement, catalog metadata, operational ownership and security rules into dedicated contracts. Use a single ingestion file for small workloads, or a bundle when different teams need different review and application workflows.

Contract files

*.ingestion.yaml

Ingestion

Executable source, target, write mode, transforms, quality rules, schema policy, execution windows and runtime behavior.

*.annotations.yaml

Annotations

Catalog-facing descriptions, aliases, tags, PII classification and lifecycle metadata for tables and columns.

*.operations.yaml

Operations

Ownership, support groups, criticality, expected frequency, freshness SLA, runbook and dashboard tags.

*.access.yaml

Access

Grants, row filters, column masks and access drift policy, applied by a workflow with the right catalog privileges.

Bundle layout

contracts/
  silver/
    s_customers.ingestion.yaml
    s_customers.annotations.yaml
    s_customers.operations.yaml
    s_customers.access.yaml

When to split contracts

Change typeContractReason
Source, target, mode, keys, quality, transform or execution behavioringestionIt changes how data is read, shaped, validated or written.
Description, aliases, tags, PII or deprecation metadataannotationsIt describes the table or fields without changing the data pipeline.
Owner, support group, criticality, SLA, runbook or alert intentoperationsIt changes how the table is operated and monitored.
Privileges, row filters or masksaccessIt requires security-oriented review and often elevated catalog privileges.

Shared metadata

Every contract file may include _metadata. ContractForge strips it before execution and keeps it for audit and bundle checks.

_metadata:
  contract_version: 1.0.0
  last_updated_by: data-platform
  last_updated_at: "2026-05-17T12:00:00Z"

Validation workflow

contractforge validate contracts/silver/s_customers.ingestion.yaml
contractforge validate-bundle contracts/silver/s_customers
contractforge governance-check contracts/silver/s_customers
contractforge apply-access contracts/silver/s_customers