Convenções de nomes para chaves JSON: camelCase vs snake_case em APIs

Não existe um padrão oficial para nomenclatura de chaves JSON. A especificação JSON apenas diz que as chaves são strings — não determina uma convenção de estilo. Na prática, duas convenções dominam: camelCase e snake_case.

O que as grandes APIs usam

API / Plataforma	Convenção	Exemplo
Google APIs	camelCase	{"userId": 1, "displayName": "Alice"}
Twitter/X API	snake_case	{"user_id": 1, "screen_name": "alice"}
GitHub API	snake_case	{"login": "alice", "avatar_url": "..."}
Stripe API	snake_case	{"customer_id": "cus_123", "created_at": 1234}
Firebase	camelCase	{"createdAt": "...", "userId": "abc"}
AWS APIs	PascalCase	{"InstanceId": "i-123", "State": "running"}

Argumentos a favor do camelCase

• Nativo em JavaScript — nenhuma conversão necessária no código frontend
• Recomendado pelo Google JSON Style Guide
• Mais curto que snake_case (sem underscores)
• Encaixa naturalmente em APIs consumidas principalmente por clientes web/mobile

Argumentos a favor do snake_case

• Mais legível — underscores criam fronteiras visuais entre palavras
• Nativo em Python, Ruby e SQL — nenhuma conversão necessária no backend
• Usado pela maioria das maiores APIs (GitHub, Twitter, Stripe)
• Consistente com nomes de colunas de banco de dados (que quase sempre são snake_case)

A verdadeira resposta: adapte-se ao seu stack

A melhor convenção depende de onde o JSON é produzido e consumido:

Cenário	Recomendado	Por quê
Backend JavaScript + frontend JavaScript	camelCase	Nenhuma conversão necessária em lugar nenhum
Backend Python/Ruby + qualquer frontend	snake_case	Coincide com idiomas do backend; frontends podem converter
API pública para muitas linguagens	snake_case	Mais universalmente legível
Microsserviços internos	Qualquer um (o importante é a consistência)	Consistência interna é o mais importante

Conversão na fronteira

Na prática, muitas equipes convertem chaves JSON na fronteira da API. Um backend Python retorna snake_case, e um middleware ou utilitário do lado do cliente converte para camelCase para o frontend React. Bibliotecas como humps (JavaScript) e djangorestframework-camel-case (Python) automatizam esse processo.

Regras para boas chaves JSON

• Seja consistente. Não misture userId e user_name na mesma resposta.
• Use nomes descritivos. createdAt em vez de ca.
• Evite abreviações. organizationId em vez de orgId.
• Use plural para arrays. items em vez de item para uma lista.
• Evite aninhamento maior que 3 níveis. Aplaine quando possível.

Converta chaves JSON instantaneamente

Use nosso conversor de chaves JSON para camelCase ou chaves JSON para snake_case. Para texto simples, experimente o conversor camelCase ou o hub de conversão de case.