How to Format JSON: Methods, Tools & Best Practices

Por qué es importante formatear JSON

JSON sin formato es técnicamente válido, pero es hostil para los humanos. Un bloque de una sola línea de objetos y arreglos anidados es casi imposible de escanear durante una sesión de depuración, y convierte las revisiones de código en juegos de adivinanza.

JSON correctamente formateado te brinda tres beneficios inmediatos: legibilidad — puedes rastrear visualmente la jerarquía de claves y valores; depurabilidad — las herramientas de diferencias y los mensajes de error hacen referencia a números de línea que realmente significan algo; y colaboración — los compañeros de equipo que revisan tus respuestas de API o archivos de configuración pueden entenderlos de un vistazo.

El formateo también previene errores sutiles. Cuando JSON está minimizado, es fácil pasar por alto un corchete mal colocado o una clave duplicada. Expandir la estructura hace que esos problemas salten a la vista.

Las reglas del formateo de JSON

Antes de alcanzar una herramienta, es útil entender lo que realmente significa "JSON formateado". La especificación de JSON (RFC 8259) no exige ninguna regla de espacio en blanco: el formateo es puramente una cuestión de presentación. Dicho esto, la comunidad ha acordado convenciones claras:

• Cada par clave-valor se coloca en su propia línea.
• Los objetos y arreglos anidados están indentados un nivel más profundo que su padre.
• Un dos puntos sigue a la clave, separado por un solo espacio: “clave”: “valor”.
• Las comas aparecen al final de cada línea (no al principio).
• Las llaves y corchetes de apertura permanecen en la misma línea que la clave; los de cierre se alinean con el nivel de indentación del padre.

Aquí hay un ejemplo mínimo. Este JSON minimizado:

{"name":"Alice","age":30,"roles":["admin","editor"],"address":{"city":"Portland","state":"OR"}}

Se convierte en esto cuando se formatea con una indentación de 2 espacios:

{
  "name": "Alice",
  "age": 30,
  "roles": [
    "admin",
    "editor"
  ],
  "address": {
    "city": "Portland",
    "state": "OR"
  }
}

Las 3 formas de formatear JSON

Cada enfoque cae en uno de tres grupos: herramientas en línea, utilidades de línea de comandos o formateo programático dentro de tu código de aplicación. La elección correcta depende de dónde te encuentres en tu flujo de trabajo y con qué frecuencia necesites hacerlo.

1. Herramientas en línea

Los formateadores basados en navegador son el camino más rápido cuando solo necesitas imprimir de forma bonita una carga útil única: pégala, haz clic en un botón, copia el resultado. No hay nada que instalar y no hay cambio de contexto a una terminal.

Las herramientas en línea funcionan bien para depuración rápida, compartir fragmentos formateados con partes interesadas no técnicas, o cuando estás en una máquina donde no puedes instalar software. La desventaja es que no se integran en tuberías automatizadas.

Pruébalo tú mismo: Pega cualquier JSON en nuestro Formateador de JSON para embellecerlo instantáneamente con tu elección de indentación.

2. Herramientas de línea de comandos

Si vives en la terminal, dos comandos cubren casi todas las necesidades de formateo:

Módulo json.tool integrado de Python — disponible en cualquier máquina con Python instalado, sin paquetes adicionales requeridos:

echo '{"name":"Alice","age":30}' | python -m json.tool

Esto produce JSON bien indentado en stdout. Puedes canalizar un archivo a través de él tan fácilmente:

python -m json.tool data.json > data-formatted.json

jq — un procesador de JSON ligero y diseñado para un propósito específico. El comando de formateo más simple es solo el filtro de identidad:

cat data.json | jq '.'

jq también agrega resaltado de sintaxis en la mayoría de las terminales, y puedes encadenar filtros para transformar y formatear en un solo paso. Es la opción preferida para scripts de shell que procesan JSON.

Ambos comandos se pueden encadenar en tuberías de CI. Por ejemplo, podrías ejecutar jq --sort-keys . en un gancho de pre-commit para asegurar que todos los archivos de configuración JSON en un repositorio estén formateados de manera consistente.

3. Formateo programático

Cuando estás escribiendo código de aplicación, formatear JSON es una línea en la mayoría de los lenguajes.

JavaScript / TypeScript:

const formatted = JSON.stringify(data, null, 2);

El tercer argumento de JSON.stringify controla la indentación. Pasa 2 para 2 espacios, 4 para 4 espacios, o "\t" para tabulaciones.

Python:

import json

formatted = json.dumps(data, indent=2, ensure_ascii=False)

Go:

formatted, err := json.MarshalIndent(data, "", "  ")

El formateo programático es esencial cuando generas JSON como parte de tu aplicación: escribiendo archivos de configuración, creando respuestas de API, o generando documentación. Tú controlas completamente la salida.

Comparando enfoques de formateo

Aquí hay una referencia rápida para ayudarte a elegir el método adecuado para la situación:

Criterio	Herramienta en línea	CLI (jq / json.tool)	Programático
Facilidad de uso	Pegar y hacer clic	Comando de una línea	Requiere contexto de código
Velocidad para tareas únicas	Más rápido	Rápido	Más lento (necesita un script)
Automatización / CI	No adecuado	Excelente	Excelente
Personalización	Limitada	Moderada (flags)	Control total
Funciona sin conexión	No	Sí	Sí
Maneja archivos grandes	Límites del navegador	Funciona bien con flujos	Depende de la implementación

El debate sobre la indentación: 2 espacios vs 4 espacios vs tabulaciones

Este es uno de esos debates que genera más calor que luz, pero hay razones prácticas para preferir cada opción.

2 espacios

La opción más común en JSON. Mantiene las estructuras profundamente anidadas compactas mientras proporciona una jerarquía visual clara. La mayoría de las herramientas del ecosistema de JavaScript (ESLint, Prettier, package.json de npm) utilizan 2 espacios por defecto. Si trabajas con APIs web o proyectos de Node.js, este es el valor predeterminado seguro.

4 espacios

Popular en flujos de trabajo relacionados con Python y algunas empresas de Java. El ancho adicional hace que los niveles de anidación sean más obvios, lo que puede ayudar al leer archivos de configuración grandes. La desventaja es que JSON profundamente anidado se desplaza rápidamente hacia el borde derecho de la pantalla.

Tabulaciones

Las tabulaciones permiten a cada desarrollador establecer su propio ancho visual en su editor. Esto suena ideal en teoría, pero en la práctica, la mayoría de las herramientas y linters de JSON esperan espacios. Las tabulaciones también se representan de manera inconsistente en los visores de diferencias basados en la web y en PRs de GitHub.

Cuándo usar cada uno:

• 2 espacios — proyectos web, bases de código de JavaScript/TypeScript, cargas útiles de API. El estándar de la comunidad.
• 4 espacios — equipos con enfoque en Python, archivos de configuración grandes donde la claridad gana sobre la compacidad.
• Tabulaciones — monorepos con preferencias de lenguaje mixtas y estrictos requisitos de accesibilidad (las tabulaciones permiten anchos configurables por el usuario).

Lo más importante es la consistencia dentro de un proyecto. Elige uno y hazlo cumplir.

Ordenando claves

La mayoría de los formateadores ofrecen una opción de "ordenar claves" que alfabetiza las claves de los objetos. Esto no es solo cosmético: tiene beneficios reales para el control de versiones.

Cuando las claves están ordenadas, las diferencias se vuelven significativas. Sin ordenación, dos desarrolladores podrían agregar las mismas claves en diferentes órdenes, produciendo diferencias ruidosas que oscurecen el cambio real. Las claves ordenadas eliminan esto por completo.

Las claves ordenadas también facilitan escanear archivos de configuración grandes. Si conoces la clave que estás buscando, puedes saltar a su posición alfabética sin buscar.

La única advertencia: algunos archivos JSON tienen un orden de claves intencionado (como un package.json donde name y version vienen primero por convención). En esos casos, preserva el orden original.

En jq, ordena las claves con:

jq --sort-keys '.' data.json

En JavaScript, pasa una función de reemplazo o usa una biblioteca como json-stable-stringify para un orden de claves determinista.

Auto-formato al guardar en VS Code

El mejor formateo es el tipo que nunca piensas. VS Code puede formatear automáticamente los archivos JSON cada vez que los guardas. Aquí te explicamos cómo configurarlo:

Paso 1: Abre tus configuraciones (Cmd+, en macOS, Ctrl+, en Windows/Linux) y agrega estas entradas:

{
  "editor.formatOnSave": true,
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  }
}

Paso 2: Instala la extensión Prettier - Code formatter si aún no lo has hecho. Maneja el formateo de JSON junto con todos los demás lenguajes en tu proyecto.

Paso 3: Crea un archivo .prettierrc en la raíz de tu proyecto para estandarizar configuraciones en todo el equipo:

{
  "tabWidth": 2,
  "useTabs": false
}

Ahora, cada archivo JSON en el proyecto se formatea de manera idéntica, independientemente de quién lo haya editado. No más diferencias solo de formateo en las solicitudes de extracción.

Manejo de casos especiales

La mayoría de las herramientas de formateo manejan JSON estándar sin problemas, pero algunas situaciones pueden complicarte:

• Números grandes — JSON no distingue entre enteros y flotantes. Algunos formateadores pueden reformatear 1.0 como 1 o perder precisión en enteros muy grandes. Si la precisión importa, verifica la salida.
• Escapes de Unicode — Un formateador podría convertir \u00e9 al carácter literal é o viceversa. Ambos son JSON válidos, pero el cambio puede causar diferencias inesperadas.
• Objetos y arreglos vacíos — Algunos formateadores expanden {} a múltiples líneas. Otros los mantienen compactos. Esta es una preferencia de estilo, pero ten en cuenta que puede variar entre herramientas.
• Nueva línea final — La convención POSIX dice que los archivos de texto deben terminar con una nueva línea. La mayoría de los formateadores añaden una, pero no todos. Verifica tu .editorconfig si esto importa para tu CI.

Formateo como parte de tu flujo de trabajo

Los equipos más efectivos tratan el formateo de JSON de la misma manera que tratan el formateo de código: como una parte automatizada y no negociable del proceso de desarrollo.

Ganchos de pre-commit: Usa una herramienta como husky con lint-staged para ejecutar Prettier o jq en archivos JSON antes de cada commit. Esto captura problemas de formateo antes de que entren en la base de código.

Verificaciones de CI: Agrega una verificación de formateo a tu tubería de CI que falle si algún archivo JSON no está correctamente formateado. Prettier tiene una bandera --check precisamente para este propósito.

Integración en el editor: Formatear al guardar elimina completamente el formateo manual. Combinado con un archivo de configuración compartido, asegura que cada miembro del equipo produzca una salida idéntica.

El objetivo es hacer que el formateo sea invisible: algo que sucede automáticamente, para que los desarrolladores puedan centrarse en el contenido real de sus archivos JSON en lugar de en cómo se ven.

Pruébalo tú mismo: Pega JSON sin formato en nuestro Formateador de JSON para embellecerlo instantáneamente. También puedes validar tu JSON para detectar errores estructurales antes de formatear.