Formatear JSON es añadir los saltos de línea y la sangría que la máquina no se molestó en poner, para que una línea de 40.000 caracteres pase a tener una forma visible. Todos los editores y la mayoría de las terminales lo hacen con un solo comando. Las únicas decisiones reales son cuánto sangrar y si pegar los datos en un sitio web para conseguirlo.
La respuesta rápida
- En una terminal:
jq . file.json, opython3 -m json.tool file.json. - En VS Code: abre el archivo y pulsa Shift+Alt+F (Shift+Option+F en Mac).
- En un navegador: abre la URL del
.jsonen Firefox, que trae un visor de JSON integrado, y pulsa Pretty Print. - En el teléfono: una app de JSON con un comando Beautify, en lugar de pegar el texto en un sitio web.
- No se formatea en absoluto: todavía no es JSON válido. Arréglalo primero; el mensaje de error del formateador te dice dónde.
Qué cambia el formateo y qué no
Dar formato solo añade o quita espacio en blanco entre tokens: espacios, tabulaciones y saltos de línea fuera de las cadenas. Un formateador correcto nunca toca los valores. Así que estos dos son el mismo documento:
{"id":7,"tags":["a","b"],"owner":{"name":"Ana"}}
{
"id": 7,
"tags": [
"a",
"b"
],
"owner": {
"name": "Ana"
}
}
Minificar es lo contrario: quitar todo espacio y salto de línea opcional. Es lo que se envía por una red o se pega en un campo de configuración que quiere una sola línea. Ninguna de las dos direcciones cambia lo que significan los datos, por eso es seguro reformatear un archivo que no escribiste tú.
Dos operaciones están junto al formateo en la mayoría de las herramientas y sí son cambios, aunque inofensivos: ordenar las claves, que reordena alfabéticamente cada objeto, y escapar, que convierte todo el documento en una sola cadena. Hazlas a propósito, no como efecto secundario.
En una terminal
jq es el que conviene tener instalado:
jq . data.json # pretty, 2-space indent
jq --indent 4 . data.json # 4 spaces
jq --tab . data.json # tabs
jq -c . data.json # minified, one line
jq -S . data.json # keys sorted A–Z
Para formatear un archivo en el mismo lugar, escribe en un archivo temporal y
muévelo de vuelta. jq . data.json > data.json vacía el archivo antes de que
jq lo lea.
jq . data.json > tmp.json && mv tmp.json data.json
Python trae un formateador, así que funciona en cualquier equipo con Python 3:
python3 -m json.tool data.json
python3 -m json.tool --indent 4 --sort-keys data.json
python3 -m json.tool --compact data.json
Una diferencia que importa con datos reales: json.tool lee los números como
floats de Python salvo que sean enteros, así que un valor como 1.10 sale como
1.1. jq 1.7 y posteriores conservan los literales numéricos tal como están
escritos. Si el archivo tiene precios, números de versión o IDs con dígitos
iniciales que importan, revisa la salida.
En un editor
VS Code: Shift+Alt+F formatea todo el documento, o Format Selection
desde la paleta de comandos formatea una parte. Activa
"editor.formatOnSave": true para los archivos [json] si los editas a menudo.
La sangría sigue el ajuste de tamaño de tabulación del editor.
Sublime Text, Notepad++, los IDE de JetBrains formatean JSON, ya sea de forma integrada (JetBrains: Code → Reformat Code) o con un plugin que se instala en una línea (Notepad++: JSON Viewer o JSTool).
Prettier es la herramienta adecuada cuando el JSON de todo un proyecto
debe verse igual: npx prettier --write "**/*.json".
En un navegador
Firefox formatea automáticamente cualquier respuesta JSON, con una pestaña JSON plegable, una pestaña Raw Data y un botón Pretty Print. Es la forma más rápida de leer una respuesta de API sin instalar nada.
Chrome y Edge muestran una casilla Pretty-print sobre el JSON sin procesar en las versiones recientes. Cualquier cosa más (plegar, buscar por clave) necesita una extensión.
La cuestión de los formateadores en línea
Busca este tema y la primera página son sitios web con una caja de texto enorme. Funcionan. La pregunta es qué estás pegando en ellos.
Una respuesta de API con un token de acceso, un archivo de configuración con la contraseña de una base de datos, una exportación de clientes: todo esto se pega rutinariamente en formateadores, y desde la página no tienes forma de verificar si el texto se queda en tu navegador o se envía a un servidor y se registra. Además, a algunos sitios los han pillado guardando documentos «compartidos» en URL fáciles de adivinar.
La regla es sencilla. Si no lo pegarías en un chat público, formatea en local. Todas las opciones de arriba se ejecutan en tu propio equipo.
Elegir una sangría
- 2 espacios es el valor por defecto de facto: jq, Prettier, la mayoría de las herramientas de JavaScript, la mayoría de las docs de API.
- 4 espacios se lee mejor en documentos muy anidados en una pantalla ancha, y es la convención de Python.
- Tabulaciones dejan que cada lector elija su propio ancho y hacen los archivos un poco más pequeños.
Ninguna está mal. Elige una por proyecto y deja que un formateador la imponga, para que un diff muestre cambios en los datos y no cambios en el espacio en blanco.
En iPhone y iPad
El teléfono es donde el JSON es menos legible, porque iOS muestra un archivo
.json como texto plano sin saltos de línea. Las formas de abrir uno están
aquí; formatear es el paso siguiente.
En Smart Json, Beautify reformatea el documento con una sangría uniforme, Minify lo reduce a una línea y Sort keys A–Z reordena cada objeto. Deshacer funciona con los tres. Si el texto no se puede analizar, un aviso nombra el problema con su línea y columna en lugar de formatear algo a medio válido, y Fix repara a los sospechosos habituales: comentarios, comas finales, comillas simples y claves sin comillas.
Beautify, Minify y Sort keys en iPhone y iPad, sin conexión, con un error en lenguaje claro cuando el JSON está roto. No se pega nada en un sitio web.
Qué haceCuando el formateo falla
Un formateador rechaza todo lo que no sea JSON válido, y su error suele ser una posición: line 1, column 3,912. En un documento minificado eso es una sola línea, así que la pista es la columna. Las causas habituales son una coma final, comillas simples, un comentario o un valor sin comillas. Cada error común se explica aquí, con lo que significa cada mensaje.