Mejores prácticas de formateo JSON — indentación, legibilidad y los debates que no mueren

La gramática de JSON es mínima. Seis tipos de valores, sin comentarios, sin comas finales, sin flexibilidad en cómo se citan las cadenas. Esa rigidez es su fortaleza para máquinas y su debilidad para humanos. Cuando un humano tiene que leer o escribir JSON — en un archivo de configuración, una respuesta de API, un diff — el formateo importa.

Esta publicación cubre cada decisión de formateo que enfrentarás, lo que el ecosistema decidió, y dónde los debates aún continúan.

Indentación: 2 espacios es el ganador

La guerra de Pestañas vs Espacios tiene un ganador en el mundo JSON: 2 espacios. Casi cada guía de estilo, linter y formateador predeterminado usa indentación de 2 espacios:

• Guía de estilo JSON de Google — 2 espacios
• Prettier — 2 espacios (predeterminado)
• ESLint — 2 espacios (la mayoría de configuraciones)
• AWS CloudFormation — 2 espacios
• Manifiestos de Kubernetes — 2 espacios

La razón es práctica: JSON ya es verboso con sus comillas y llaves. La indentación de 4 espacios empuja los objetos anidados fuera del borde derecho de la mayoría de editores. 2 espacios mantiene las cosas legibles sin desperdiciar espacio horizontal.

Usa 4 espacios si tu equipo lo prefiere y eres consistente. Usa pestañas si debes, pero sé consciente de que la mayoría de herramientas JSON asumen espacios, y la indentación mixta en un archivo JSON es un error de análisis esperando ocurrir.

Comas finales: aún no

JSON no permite comas finales. Este es el error de sintaxis más común en archivos JSON editados manualmente. Escribes:

{
  "name": "Alice",
  "items": ["a", "b",],
}

Y un analizador estricto lo rechaza. La coma final después de "b" y la coma final después del } de cierre son ambas ilegales.

YAML permite comas finales (y la mayoría de lenguajes lo hacen). JSON no. Si tus herramientas soportan JSONC (JSON con Comentarios, usado en tsconfig.json y settings.json de VS Code), las comas finales están permitidas. Pero JSON puro — el tipo que viaja por APIs — no las tolera.

La mejor defensa: usa un formateador que detecte esto automáticamente. Pega tu JSON en un validador antes de confirmar.

Bonito vs compacto

JSON bonito tiene nuevas líneas e indentación. Es legible, tiene diferencias y se puede depurar:

{
  "status": "ok",
  "count": 42
}

JSON compacto no tiene espacio en blanco entre tokens. Es más pequeño en la red:

{"status":"ok","count":42}

La regla general:

• Dirigido a humanos (archivos de configuración, registros, respuestas de API durante depuración) → bonito.
• Dirigido a máquinas (payloads de API en producción, colas de mensajes, flujos de eventos) → compacto.
• Almacenamiento (bases de datos, cachés) → compacto, a menos que necesites leerlo manualmente durante depuración.

JSON compacto ahorra aproximadamente un 20-30% en tamaño comparado con JSON bonito de 2 espacios. Para un payload de 10KB, eso es 2-3KB. Sobre millones de solicitudes, se suma. Para un archivo de configuración que editas a mano, la legibilidad de JSON bonito vale los bytes extra.

Claves ordenadas

¿Las claves de objeto deben ordenarse alfabéticamente?

A favor: los diffs son deterministas. Si agregas una clave, solo esa línea aparece en un diff de git. Sin claves ordenadas, insertar una clave en el medio puede cambiar cada clave subsiguiente, creando un diff ruidoso.

En contra: la agrupación lógica es más legible. Poner "name" primero e "id" segundo es intuitivo. La ordenación alfabética pone "address" antes que "name" sin razón semántica.

La respuesta pragmática: ordena claves en JSON generado por máquina (APIs, configuraciones, diffs). Mantén el orden lógico en JSON escrito a mano. La mayoría de formateadores (Prettier, jq, python -m json.tool) tienen un indicador --sort-keys que puedes habilitar en CI.

Convenciones de nombres de claves

Las claves de JSON son cadenas, y el ecosistema se ha decidido por dos convenciones:

• camelCase — el predeterminado de JavaScript/Node.js. firstName, lastName, createdAt.
• snake_case — el predeterminado de Python/Ruby/Rust. first_name, last_name, created_at.
• kebab-case — raro en JSON, más común en URLs y CSS. Evítalo para claves de API.

Elige una y mantenla. La mayoría de APIs usan camelCase. Si estás construyendo una API REST para consumidores de JavaScript, camelCase es el camino de menor resistencia. Si estás interfazando con servicios de Python, snake_case reduce la fricción.

Lo peor que puedes hacer es mezclarlos: firstName en un endpoint, last_name en otro. Elige una convención, imponla con un linter, y sigue adelante.

Formateo de números

JSON no distingue enteros de flotantes. 42 y 42.0 son ambos válidos, y la mayoría de analizadores los tratan idénticamente. Pero el formateo importa para legibilidad:

• Enteros: sin punto decimal. 42, no 42.0.
• Flotantes: usa tantos dígitos como necesites. 3.14159, no 3.14159000000000.
• Números grandes: usa notación científica si el número es enorme. 1e10 es más claro que 10000000000.

JSON no soporta Infinity, -Infinity o NaN. Si tu lenguaje serializa estos, la salida no es JSON válido y los analizadores lo rechazarán.

Cadenas: comillas simples vs dobles

JSON requiere comillas dobles para cadenas. Esto no es negociable. 'hello' no es JSON válido. "hello" lo es.

Si tu linter o editor permite comillas simples en archivos JSON, está analizando JSONC o un superconjunto, no JSON estándar. Las APIs y analizadores que esperan JSON estricto rechazarán cadenas con comillas simples.

Comentarios: aún no permitidos

JSON no tiene sintaxis de comentarios. Esto es por diseño (el estándar dice que JSON es “un formato de intercambio de datos”, no un lenguaje de configuración), pero es la queja más común de desarrolladores que usan YAML.

Soluciones alternativas:

• Usa una clave "comment" o "_comment". Es feo pero válido.
• Usa JSONC (el formato de VS Code) si tus herramientas lo soportan.
• Cambia a YAML o TOML para archivos de configuración donde los comentarios importan.

El flujo de trabajo del formateador

El mejor flujo de trabajo para formateo JSON:

1. Escribe JSON como quieras. No pierdas tiempo indentando a mano.
2. Ejecuta un formateador al guardar. Prettier, jq o el formateador incorporado de tu editor.
3. Confirma la salida formateada. Diffs consistentes, sin debates de estilo.
4. Valida en CI. Un paso de lint JSON detecta comas finales y errores de sintaxis antes de que lleguen a producción.

Esto elimina cada debate de formateo. El formateador decide, todos los demás escriben código.

Errores comunes

• Comas finales — el error de análisis más frecuente en JSON editado manualmente.
• Comillas simples — válidas en literales de objeto JavaScript, inválidas en JSON.
• Claves sin comillas — { name: "Alice" } es JavaScript, no JSON.
• Comentarios — // esto no es JSON ni /* esto tampoco */.
• Indentación mixta — mezclar pestañas y espacios en el mismo archivo.

Pega tu JSON en un validador antes de desplegar. Toma un segundo y ahorra treinta minutos depurando un error 400 misterioso.