Uma alteração de campo na API pode parecer inofensiva para quem produz o dado e ainda quebrar um painel executivo semanas depois. Consumidores analíticos dependem de significado, comportamento de nulos, unidades e prazos de entrega que não aparecem em um exemplo JSON. O contrato de dados explicita essas expectativas e dá às equipes um caminho mais seguro para evoluir.
Um contrato útil descreve nome do campo, tipo, obrigatoriedade, semântica de nulo, unidade, valores aceitos, responsável, classificação de sensibilidade, expectativa de atualização e política de compatibilidade. Em eventos, inclua identidade, ordenação e possibilidade de duplicidade. Em APIs, documente requisição, resposta, erros e paginação, não apenas o formato.
| Mudança | Questão estrutural | Questão de negócio |
|---|---|---|
| Adicionar campo opcional | Leitores antigos conseguem ignorá-lo? | Modelos downstream deixam de ver uma dimensão importante? |
| Renomear ou remover campo | Consumidores antigos ainda interpretam o payload? | Quais relatórios dependem do significado anterior? |
| Número vira texto | O validador aceita o novo esquema? | Ordenação, agregação e unidade continuam corretas? |
| Mudar opções de enum | Valores desconhecidos são aceitos? | Painéis classificam os novos estados corretamente? |
| Mudar timestamp | O valor continua sendo data válida? | Fuso ou evento vs processamento mudou de sentido? |
Compatibilidade retroativa ajuda, mas as regras exatas variam entre JSON Schema, Avro, Protobuf e configurações do registry. Uma mudança estruturalmente válida ainda pode mudar o significado de negócio. Mantenha definições semânticas e exemplos ao lado do esquema e teste validação e expectativas downstream.
Versione contratos no controle de código, atribua responsável ao produtor e liste consumidores críticos. Pull requests devem executar validação sintática, checagem de compatibilidade e testes representativos de analytics. Uma mudança incompatível precisa identificar consumidores afetados, oferecer janela de migração e, se possível, publicar versão nova antes de aposentar a antiga.
Preserve registros brutos com horário de ingestão e versão do esquema para permitir replay após corrigir transformações. Não converta silenciosamente valores inválidos em zero ou texto vazio: direcione-os para quarentena com contagens e amostras sem dados sensíveis.
Meça falhas de validação, campos ou enums desconhecidos, mudança na taxa de nulos, atraso de atualização, variação de volume e erros dos modelos consumidores. Relacione alertas ao conjunto de dados e ao responsável. Registre linhagem da API ou tópico até as tabelas e a métrica. Diante de uma alteração no painel, a equipe deve localizar versão e janela de origem.
O produtor responde pela semântica da fonte e por avisar mudanças; analytics, pelas transformações e definições de negócio; a plataforma, por validação, armazenamento e entrega. Contratos funcionam com responsáveis nomeados e revisão, não como arquivo sem fiscalização.
Veja também a evolução de relatórios de Sheets para SQL e relatórios operacionais com APIs, ETL e SQL.
O contrato conecta a API de origem às decisões analíticas. Versione expectativas estruturais e semânticas, teste compatibilidade na CI, preserve dados brutos reproduzíveis e monitore qualidade e atualização com linhagem. Assim, uma mudança vira migração revisada, não surpresa no dashboard.