Annotations contract.

Annotations describe the table and its fields. They are catalog/governance metadata, not ingestion behavior. Use them for descriptions, aliases, tags, PII classification and lifecycle metadata.

Complete example

YAML

_metadata:
  contract_version: 1.0.0

policy: warn
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

Python

from contractforge import ingest

result = ingest(
    source="main.raw.customers",
    catalog="main",
    target_schema="crm_curated",
    target_table="s_customers",
    mode="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"},
            },
        },
    },
)

In bundle mode, the matching *.ingestion.yaml owns the target table. Keep target out of the annotations file unless you intentionally want an explicit compatibility assertion.

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.