Mejores prácticas de formato JSON: legible, válido y eficiente
Respuesta rápida
Utilice sangría de 2 espacios para JSON legible por humanos, sin comas al final, claves entre comillas dobles y un orden de claves coherente (alfabético o significativo para el dominio). Minimice JSON para transporte de producción y Pretty-print para desarrollo. Utilice nuestro formateador JSON gratuito para cambiar entre los dos al instante.
Introducción
Las opciones de formato JSON afectan la legibilidad, el tamaño del archivo y la velocidad de depuración. Si bien la sintaxis JSON está estrictamente definida por RFC 8259, cómo aplicar sangría, ordenar claves y manejar espacios en blanco es una cuestión de convención. Esta guía explica las mejores prácticas ampliamente adoptadas para que su JSON sea consistente en todos los equipos, fácil de depurar y eficiente a través de la red.
Paso a paso
-
Elija un ancho de sangría
2 espacios es la convención más común (Prettier, ESLint, Google JSON Style Guide). 4 espacios son aceptables para configuraciones profundamente anidadas. Se desaconsejan las pestañas porque la representación varía según el editor. Elija uno y aplíquelo en todo el proyecto.
-
Ordene las claves consistentemente
Ordene las claves alfabéticamente para obtener resultados deterministas (útil para almacenamiento en caché y diferencias) o agrúpelas por significado de dominio (identificación primero, luego atributos, luego relaciones). Evite el orden de claves aleatorio: hace que las diferencias sean ruidosas y rompe las pruebas de instantáneas.
-
Minimizar para transporte de producción
La JSON minimizada elimina todos los espacios en blanco no esenciales, lo que reduce el tamaño de la carga útil entre un 10 y un 0 %. Publique JSON minificado de APIs en producción y mantenga JSON bien impreso solo para desarrollo local y depuración.
-
Validar antes de enviar
Ejecute siempre JSON a través de un validador antes de enviarlo a un API o escribir en un archivo de configuración. Una sola coma al final o una clave sin comillas hará que JSON.parse() arroje y rompa al consumidor.
-
Utilice un formateador para cambiar de modo
Pegue su JSON en el formateador JSON para embellecerlo para leerlo o minimizarlo para transportarlo. La herramienta valida la sintaxis e informa la ubicación exacta de cualquier error, lo que ahorra tiempo de depuración.
Ejemplos
Bonito impreso (sangría de 2 espacios)
Aporte: {"id":1,"name":"Alice","active":true}
Producción: {
"id": 1,
"name": "Alice",
"active": true
}
Minimizado para producción
Aporte: {
"id": 1,
"name": "Alice"
}
Producción: {"id":1,"name":"Alice"}
Claves ordenadas alfabéticamente
Aporte: {"zebra":1,"apple":2,"mango":3}
Producción: {"apple":2,"mango":3,"zebra":1}
Problemas comunes
- Las comas finales: {"a":1,} no son válidas JSON. La mayoría de los formateadores los eliminan, pero los analizadores estrictos como JSON.parse() rechazarán la entrada.
- Comillas simples y claves sin comillas: {'a':1} y {a:1} son JavaScript válido pero JSON no válido. Utilice siempre comillas dobles para claves y valores de cadena.
- Comentarios en JSON: el estándar JSON no permite // o /* */ comentarios. Utilice JSONC, JSON5 o un archivo de esquema independiente si necesita documentación en línea.
- Sangría mixta: mezclar tabulaciones y espacios rompe las herramientas de diferenciación y puede causar errores de pelusa de "sangría inconsistente". Normalice con un formateador antes de confirmar.
Consejos
- Configure su editor para formatear JSON al guardar con sangría de 2 espacios; esto evita debates de estilo en la revisión del código.
- Para respuestas API, establezca Tipo de contenido: aplicación/json; charset=utf-8 y servir JSON minificado con compresión gzip/Brotli para máxima eficiencia.
- Utilice un orden de claves determinista (por ejemplo, alfabético) cuando JSON se aplica mediante hash o se compara en pruebas instantáneas: el orden aleatorio provoca errores de falsos positivos.
- Al depurar una carga útil JSON grande, imprímala primero y luego use expresiones regulares o jq para extraer el subárbol relevante en lugar de escanear a ojo.