100%
Voltar ao catálogo de notas

Nota técnica

Nota plataforma

Data Contracts System: qualidade entre sistemas e pipelines

Contratos versionados (schema, SLAs, owners) entre produtores e consumidores de dados — padrão de empresa madura aplicável a APIs, pipelines e integrações.

7 min de leitura media planejamento
data-contracts governanca schema api pipeline documentacao
Stack: JSON Schema / Avro / Protobuf Git CI OpenAPI dbt ou validação custom

Visão geral

Sistema (ou framework interno) para formalizar acordos de dados: o que o produtor garante (schema, volume esperado, atraso máximo, política de breaking change) e o que o consumidor pode assumir. Reduz surpresa em produção e acelera onboarding de novos consumidores.

Problema

  • Mudança de coluna quebra downstream sem aviso.
  • Ninguém sabe quem é owner do dataset quando falha.
  • Integrações replicam regras duplicadas e divergem.

Componentes do contrato (mínimo viável)

  • Identificador do dataset (ex.: gold.fact_orders).
  • Schema com tipos e campos obrigatórios.
  • SLA de freshness (ex.: T+1 08:00).
  • Semântica de campos críticos (uma linha por coluna “P0”).
  • Política de versão (major = breaking; minor = compatível).
  • Contatos: owner técnico e owner de negócio.

Implementação

  1. Repositório data-contracts/ em Git (YAML + schema).
  2. CI: validação de PR que altera contrato (diff visível para consumidores).
  3. Runtime: testes de conformidade no pipeline (falhou → não publica partição).
  4. Opcional: catálogo (DataHub, OpenMetadata) linkando contrato.

Relação com Delivery-Projeto

Documentar contrato da camada Gold e da API mock; ao evoluir colunas, exigir bump de versão e nota no changelog.

MVP

  • 2 contratos reais (API mock + uma tabela Gold).
  • Check automático no pytest ou no job de build.
  • Página markdown “Como propor mudança em contrato”.

Riscos

  • Burocracia excessiva — começar só para dados P0.
  • Contratos desatualizados — CI sem uso vira papel; integrar ao deploy.

Próximo passo

Listar consumidores atuais de fact_orders (mesmo que só você + Streamlit) e definir colunas imutáveis por 30 dias.