Projetando Contratos de Dados

O que Projetando Contratos de Dados faz?

Quando usar

• Um upstream (serviço, evento, API, arquivo) alimenta pipelines downstream e uma alteração poderia quebrá-los silenciosamente.
• Definindo a interface entre um time/sistema produtor e o data warehouse.
• Adicionando imposição de esquema/qualidade na fronteira de ingestão.
• NÃO use para alterações internas modelo-a-modelo dentro de um único projeto dbt (use testes + handling-schema-evolution).

O que um contrato especifica

• Esquema: campos, tipos, nulabilidade e valores permitidos.
• Semântica: o que cada campo significa e sua unidade/granularidade.
• Garantias: frescor/SLA, expectativas de volume, unicidade de chaves.
• Responsabilidade: quem produz e a quem contatar.
• Versionamento + política de mudanças: como mudanças que quebram são comunicadas.

Fluxo de trabalho

- [ ] Escreva o contrato como um esquema versionado e versionado (não conhecimento tribal)
- [ ] Imponha-o na fronteira de ingestão (valide na chegada)
- [ ] Classifique as mudanças: aditivas (seguras) vs. quebra (precisa de nova versão)
- [ ] Em caso de violação, rejeite/coloque em quarentena e alerte o produtor
- [ ] Versione e comunique mudanças que quebram com antecedência

1. Torne-o explícito e versionado. Armazene o contrato como código (JSON Schema, esquema Avro/Protobuf ou especificação YAML) junto ao pipeline, revisado como qualquer API.
2. Imponha na fronteira. Valide os dados de entrada contra o contrato na chegada; rejeite ou coloque em quarentena violações em vez de carregá-los.
3. Classifique as mudanças. Campos aditivos/opcionais = compatível com versões anteriores. Remover campos, renomear, restringir tipos/nulabilidade = quebra → nova versão.
4. Falhe alto para o produtor, não silenciosamente downstream.

Padrões

Contrato como JSON Schema (imposto na ingestão):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["order_id", "amount", "ordered_at"],
  "properties": {
    "order_id": { "type": "string" },
    "amount": { "type": "number", "minimum": 0 },
    "ordered_at": { "type": "string", "format": "date-time" },
    "coupon": { "type": ["string", "null"] }
  },
  "additionalProperties": false
}

Ponto de imposição — valide cada registro na ingestão; direcione falhas para um local de quarentena com o motivo e alerte o time produtor. Isso transforma uma quebra silenciosa downstream em um sinal imediato e com responsável na origem.

Registro de esquemas (Kafka/Avro) — imponha compatibilidade (BACKWARD) no momento da publicação para que produtores não possam enviar um esquema incompatível.

Armadilhas comuns

• Contrato como documentação apenas — se não for imposto em código, ele se desvia e quebra silenciosamente.
• Imposição no fundo do warehouse — capture violações na fronteira, antes que dados ruins se espalhem.
• Sem versionamento — toda mudança se torna uma emergência; versione e desative gradualmente.
• additionalProperties irrestrito quando você precisa de rigidez — campos inesperados passam; defina como false onde apropriado.
• Sem responsável — um lote rejeitado sem ninguém para contatar paralisa o pipeline.
• Mudanças que quebram sem prazo de aviso — coordene produtor/consumidor via esquemas versionados e uma janela de descontinuação.