Contrato de anotações.

As anotações descrevem a tabela e seus campos. Eles são metadados de catálogo/governança, não comportamento de ingestão. Use-os para descrições, aliases, tags, classificação de PII e metadados de ciclo de vida.

Exemplo completo

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"},
            },
        },
    },
)

Em modo bundle, o *.ingestion.yaml correspondente define o target da tabela. Não coloque target no arquivo de anotações, a menos que você queira uma verificação explícita de compatibilidade.

Campos

Campo	Tipo	Padrão	Usar
_metadata	objeto		Metadados de arquivo para auditoria e verificações de pacotes.
target	objeto	opcional	Verificação de compatibilidade opcional com relação ao destino de ingestão.
target.catalog	string	catálogo de ingestão	Catálogo esperado.
target.schema	string	esquema físico de ingestão	Esquema esperado.
target.table	string	tabela de destino de ingestão	Mesa esperada.
policy	fail | warn | ignore	warn	Comportamento de falha ao aplicar anotações.
table	objeto		Anotações em nível de tabela.
table.description	string | nulo	nulo	Comentário/descrição da tabela.
table.aliases	string | lista[string]	[]	Nomes comerciais alternativos.
table.tags	objeto[string,string]		Etiquetas de catálogo. Os valores são normalizados para strings.
table.deprecated	objeto | nulo	nulo	Metadados do ciclo de vida para uma tabela obsoleta.
columns	objeto		Anotações de coluna codificadas pelo nome da coluna física.
columns.*.description	string | nulo	nulo	Comentário/descrição da coluna.
columns.*.aliases	string | lista[string]	[]	Nomes comerciais alternativos para a coluna.
columns.*.tags	objeto[string,string]		Tags de coluna. Exemplos comuns: key, required, confidentiality.
columns.*.pii	objeto | nulo	nulo	Classificação PII.
columns.*.pii.enabled	booleano	verdadeiro quando pii existe	Se a coluna contém PII.
columns.*.pii.type	enumeração	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	enumeração	internal	public, internal, restricted, confidential.
columns.*.deprecated	objeto | nulo	nulo	Metadados do ciclo de vida para uma coluna obsoleta.
deprecated.since	string	obrigatório quando obsoleto existe	Data ou versão em que a depreciação começa.
deprecated.replacement	string	obrigatório quando obsoleto existe	Tabela ou coluna de substituição.
deprecated.removal_date	string | nulo	nulo	Data de remoção planejada.