Annotations contract | ContractForge

Complete example

_metadata:
  contract_version: 1.0.0

policy: warn
target:
  catalog: main
  schema: crm_curated
  table: s_customers
table:
  description: Curated customer dimension used by CRM analytics.
  aliases: [clients, account holders]
  tags:
    domain: crm
    data_product: customer360
    contains_pii: "true"
  deprecated:
    since: "2026-05-01"
    replacement: s_customers_v2
    removal_date: "2026-12-31"
columns:
  customer_id:
    description: Stable customer business key.
    aliases: [client_id]
    tags:
      key: "true"
      required: "true"
  email:
    description: Customer email used for contactability analysis.
    pii:
      enabled: true
      type: email
      sensitivity: restricted
    tags:
      confidentiality: restricted
  legacy_code:
    description: Legacy identifier kept for reconciliation.
    deprecated:
      since: "2026-05-01"
      replacement: customer_id

from contractforge import ingest

result = ingest(
    source="main.raw.customers",
    catalog="main",
    target_schema="crm_curated",
    target_table="s_customers",
    mode="scd1_upsert",
    merge_keys=["customer_id"],
    annotations={
        "policy": "warn",
        "table": {
            "description": "Curated customer dimension used by CRM analytics.",
            "aliases": ["clients", "account holders"],
            "tags": {"domain": "crm", "data_product": "customer360", "contains_pii": "true"},
        },
        "columns": {
            "customer_id": {
                "description": "Stable customer business key.",
                "aliases": ["client_id"],
                "tags": {"key": "true", "required": "true"},
            },
            "email": {
                "description": "Customer email used for contactability analysis.",
                "pii": {"enabled": True, "type": "email", "sensitivity": "restricted"},
                "tags": {"confidentiality": "restricted"},
            },
        },
    },
)

Fields

Field	Type	Default	Use
`_metadata`	object	{}	File metadata for audit and bundle checks.
`target`	object	optional	Optional compatibility check against the ingestion target.
`target.catalog`	string	ingestion catalog	Expected catalog.
`target.schema`	string	ingestion physical schema	Expected schema.
`target.table`	string	ingestion target table	Expected table.
`policy`	`fail` \| `warn` \| `ignore`	`warn`	Failure behavior when applying annotations.
`table`	object	{}	Table-level annotations.
`table.description`	string \| null	null	Table comment/description.
`table.aliases`	string \| list[string]	[]	Alternative business names.
`table.tags`	object[string,string]	{}	Catalog tags. Values are normalized to strings.
`table.deprecated`	object \| null	null	Lifecycle metadata for a deprecated table.
`columns`	object	{}	Column annotations keyed by physical column name.
`columns.*.description`	string \| null	null	Column comment/description.
`columns.*.aliases`	string \| list[string]	[]	Alternative business names for the column.
`columns.*.tags`	object[string,string]	{}	Column tags. Common examples: `key`, `required`, `confidentiality`.
`columns.*.pii`	object \| null	null	PII classification.
`columns.*.pii.enabled`	boolean	true when `pii` exists	Whether the column contains PII.
`columns.*.pii.type`	enum	`unknown`	`address`, `bank_account`, `birth_date`, `credit_card`, `device_id`, `document`, `email`, `financial`, `health`, `ip_address`, `name`, `national_id`, `other`, `phone`, `ssn`, `tax_id`, `unknown`.
`columns.*.pii.sensitivity`	enum	`internal`	`public`, `internal`, `restricted`, `confidential`.
`columns.*.deprecated`	object \| null	null	Lifecycle metadata for a deprecated column.
`deprecated.since`	string	required when deprecated exists	Date or version where deprecation starts.
`deprecated.replacement`	string	required when deprecated exists	Replacement table or column.
`deprecated.removal_date`	string \| null	null	Planned removal date.