Nomes e capitalização consistentes nos campos JSON

O que é

O JSON (RFC 8259, citada) restringe apenas a sintaxe: objetos são pares nome/valor, os nomes são strings e os nomes dentro de um objeto devem ser únicos. A aparência dos nomes é uma questão de convenção. O Google JSON Style Guide (citado) exige que os nomes de propriedades sejam strings ASCII em camel case com semântica definida, desaconselha o agrupamento arbitrário de dados, representa valores de enum como strings e formata datas como strings RFC 3339. O mapeamento ProtoJSON (citado) serializa os nomes de campos do protobuf como chaves em lowerCamelCase, os enums pelos seus nomes e os inteiros de 64 bits como strings decimais, porque muitos consumidores de JSON não conseguem representá-los com exatidão. O snake_case (created_at) é igualmente comum. O que importa é que uma única convenção valha em todos os endpoints, incluindo corpos de erro e payloads de webhook.

Por que importa

Nomes inconsistentes são um sinal visível de uma API montada por várias equipes: os clientes precisam de código de mapeamento por endpoint, os SDKs gerados produzem identificadores estranhos e os agentes que leem a descrição não conseguem deduzir os nomes dos campos a partir de padrões.

Como aplicar

• Registre a convenção no guia de estilo da API, com exemplos: capitalização, nomes no plural para arrays (items), prefixos para booleanos (isActive, hasChildren), sufixos de unidade ou formato (durationSeconds, sizeBytes) e campos de identificador terminados em Id.
• Faça a verificação de forma automática: um linter sobre o documento OpenAPI, ou regras de nomes de campos do protobuf junto com o mapeamento ProtoJSON.
• Nomeie pelo significado, não pelo armazenamento: customerId, e não cust_fk; não renomeie o campo quando a coluna do banco de dados mudar.
• Defina os formatos de valor uma só vez: timestamps RFC 3339 com offset, sufixos de unidade explícitos ou durações ISO 8601, strings para enums em vez de números, valores monetários como strings ou como inteiros em unidades menores.
• Use o mesmo nome para o mesmo conceito em todos os recursos; owner em um recurso e ownerId em outro é um defeito.
• Trate de forma diferente os objetos JSON usados como mapas: as suas chaves são dados e não seguem nenhuma regra de nomenclatura, e a documentação deve indicar quais objetos são mapas.

Armadilhas

Renomear um campo para corrigir a capitalização é uma mudança incompatível; adicione o novo nome e mantenha o antigo durante um período de descontinuação. Expor identificadores de implementação, como $type ou __typename, em um contrato público sem documentá-los. Abreviações que só a equipe de origem entende. Duplicatas com capitalização diferente (userId e userID) que sobrevivem porque ninguém executa um linter.