# ADR-0005 — JSON da API pública em snake_case

**Status:** Accepted  
**Data:** 2026-07-14  
**Decisores:** Arquitetura de Software

---

## Contexto

Backend Python naturalmente usa `snake_case`. Frontend TypeScript usa `camelCase`. Misturar estilos na API gera inconsistência OpenAPI e clientes.

## Decisão

A **API HTTP JSON pública** usa **`snake_case`** para nomes de campos. O frontend adapta na camada de client/SDK. Eventos de integração também usam `snake_case`.

## Alternativas consideradas

| Opção | Prós | Contras | Por que não |
|--------|------|---------|-------------|
| camelCase na API | Conforto TS | Atrito Python + divergência | Mais transforms no backend |
| aceitar ambos | “Flexível” | Ambiguidade, bugs | Proibido |
| case por versão | Migração suave | Complexidade permanente | Desnecessário agora |

## Consequências

### Positivas
- Um contrato estável.
- Alinhamento com payloads de eventos e logs.

### Negativas / riscos
- Mapping no frontend (mitigar com OpenAPI generator).

### Follow-ups
- [ ] Geração de client TS a partir do OpenAPI.

## Referências

- [Convenções de Nomenclatura](../engenharia/02-convencoes-de-nomenclatura.md)