← Notas

Nota técnica

Contratos de dados entre camadas

Schema, freshness e owner — o mínimo para o consumidor não quebrar em silêncio.

  • Python
  • JSON Schema
  • Git
6 min de leitura

  1. 01 — Problema

    Mudança de coluna na origem quebra Gold e dashboard sem aviso nem owner.

  2. 02 — Hipótese

    Um contrato versionado (schema + SLA + política de breaking change) é mais barato que retrabalho downstream.

  3. 03 — Implementação

    Identificador do dataset, campos P0, freshness e bump de versão — aplicado a fact_orders no Delivery Audit.

  4. 04 — Resultado

    Consumidor assume o grão e os campos estáveis; mudança incompatível exige versão nova.

  5. 05 — Aprendizado

    Contrato sem CI vira wiki. Tem que falhar o job se o payload não conformar.

No Delivery Audit, fact_orders é o contrato com o consumidor. Sem isso, cada evolução da API mock vira quebra de dashboard.

Problema

  • Coluna some ou muda de tipo e o job “passa”.
  • Ninguém sabe quem responde pelo dataset.
  • A mesma regra de negócio é reimplementada em Silver, no BI e na auditoria — e diverge.

Hipótese

O mínimo de um contrato:

  • identificador (gold.fact_orders);
  • schema (tipos, obrigatórios);
  • SLA de freshness;
  • semântica das colunas P0;
  • política de versão (major = breaking);
  • owner técnico.

Implementação

  1. Documento versionado no Git junto do pipeline.
  2. Validação na carga: payload fora do schema não publica a partição.
  3. Changelog quando o grão ou um campo P0 muda.

No case de delivery, o grão é um pedido. Flags de auditoria apontam para order_id. Isso é contrato, mesmo sem DataHub.

Resultado

O consumidor (Streamlit ou regra) não precisa conhecer o JSON da API. Breaking change fica explícito.

Aprendizado

Começar só nos datasets P0. Contrato em tudo, no dia um, vira burocracia que ninguém atualiza.