Convenciones de nombres para claves JSON: camelCase vs snake_case en APIs

No existe un estándar oficial para nombrar claves JSON. La especificación JSON solo dice que las claves son cadenas de texto — no establece una convención de estilo. En la práctica, dominan dos convenciones: camelCase y snake_case.

Qué usan las grandes APIs

API / Plataforma	Convención	Ejemplo
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 de camelCase

• Nativo en JavaScript — no requiere conversión en el código frontend
• Recomendado por la Google JSON Style Guide
• Más corto que snake_case (sin guiones bajos)
• Encaja naturalmente en APIs consumidas principalmente por clientes web/móvil

Argumentos a favor de snake_case

• Más legible — los guiones bajos crean límites visuales entre palabras
• Nativo en Python, Ruby y SQL — no requiere conversión en el backend
• Usado por la mayoría de las APIs más grandes (GitHub, Twitter, Stripe)
• Consistente con los nombres de columnas de bases de datos (que casi siempre son snake_case)

La verdadera respuesta: adáptate a tu stack

La mejor convención depende de dónde se produce y consume el JSON:

Escenario	Recomendado	Por qué
Backend JavaScript + frontend JavaScript	camelCase	No se necesita conversión en ningún punto
Backend Python/Ruby + cualquier frontend	snake_case	Coincide con los modismos del backend; los frontends pueden convertir
API pública para muchos lenguajes	snake_case	Más universalmente legible
Microservicios internos	Cualquiera (lo importante es la consistencia)	La consistencia interna es lo más importante

Conversión en la frontera

En la práctica, muchos equipos convierten las claves JSON en la frontera de la API. Un backend Python devuelve snake_case, y un middleware o utilidad del lado del cliente convierte a camelCase para el frontend React. Bibliotecas como humps (JavaScript) y djangorestframework-camel-case (Python) automatizan este proceso.

Reglas para buenas claves JSON

• Sé consistente. No mezcles userId y user_name en la misma respuesta.
• Usa nombres descriptivos. createdAt en lugar de ca.
• Evita abreviaturas. organizationId en lugar de orgId.
• Usa plural para arrays. items en lugar de item para una lista.
• Evita anidar más de 3 niveles. Aplana cuando sea posible.

Convierte claves JSON al instante

Usa nuestro conversor de claves JSON a camelCase o claves JSON a snake_case. Para texto plano, prueba el conversor camelCase o el hub de conversión de case.