Nomenclatura y capitalización consistentes de los campos JSON

Qué es

JSON (RFC 8259, citado) restringe únicamente la sintaxis: los objetos son pares nombre/valor, los nombres son cadenas y los nombres dentro de un objeto deberían ser únicos. El aspecto de los nombres es una cuestión de convención. La guía de estilo JSON de Google (citada) exige que los nombres de propiedad sean cadenas ASCII en camel case con una semántica definida, advierte contra la agrupación arbitraria de datos, representa los valores de enum como cadenas y da formato a las fechas como cadenas RFC 3339. El mapeo de ProtoJSON (citado) serializa los nombres de campo de protobuf como claves en lowerCamelCase, los enums por su nombre, y los enteros de 64 bits como cadenas decimales, porque muchos consumidores de JSON no pueden representarlos con exactitud. snake_case (created_at) es igual de habitual. Lo que importa es que una única convención se mantenga en todos los endpoints, incluidos los cuerpos de error y las cargas útiles de los webhooks.

Por qué importa

Los nombres inconsistentes son una señal visible de una API ensamblada por varios equipos: los clientes necesitan código de mapeo por endpoint, los SDK generados producen identificadores incómodos, y los agentes que leen la descripción no pueden inferir nombres de campo a partir de patrones.

Cómo aplicarlo

• Recoger la convención en la guía de estilo de la API con ejemplos: capitalización, nombres en plural para los arrays (items), prefijos booleanos (isActive, hasChildren), sufijos de unidad o de formato (durationSeconds, sizeBytes), campos identificadores que terminan en Id.
• Aplicarla de forma mecánica: un linter sobre el documento OpenAPI, o reglas de nombre de campo de protobuf junto con el mapeo de ProtoJSON.
• Nombrar por significado, no por almacenamiento: customerId, no cust_fk; no renombrar cuando cambia la columna de la base de datos.
• Elegir los formatos de valor una sola vez: marcas de tiempo RFC 3339 con desplazamiento horario, sufijos de unidad explícitos o duraciones ISO 8601, cadenas de enum en lugar de números, importes monetarios como cadenas o como unidades enteras menores.
• Usar el mismo nombre para el mismo concepto en todos los recursos; owner en un recurso y ownerId en otro es un defecto.
• Tratar de forma distinta los objetos JSON usados como mapas: sus claves son datos y no siguen ninguna regla de nomenclatura, y la documentación debe indicar qué objetos son mapas.

Trampas

Renombrar un campo para corregir su capitalización es un cambio incompatible (breaking change); conviene añadir el nombre nuevo y conservar el antiguo durante un período de deprecación. Filtrar identificadores de implementación como $type o __typename en un contrato público sin documentarlos. Abreviaturas que solo entiende el equipo de origen. Duplicados con capitalización distinta (userId y userID) que sobreviven porque nadie los revisa con un linter.