Cómo Formatear JSON de Forma Legible

Formatear JSON de forma legible (pretty printing) hace que los datos brutos sean legibles con sangría adecuada y saltos de línea. Esto es esencial para depuración, documentación, desarrollo de APIs y cualquier escenario donde los humanos necesiten inspeccionar datos estructurados. Sin el formateo, JSON aparece como una única línea de texto ininterrumpida que es casi imposible de analizar visualmente. Esta guía cubre todos los métodos para formatear JSON en diferentes entornos, desde herramientas en línea hasta utilidades de línea de comandos y bibliotecas de código.

¿Qué es el Formateo Legible?

El formateo legible (también llamado embellecimiento o formato) toma JSON compacto y añade espacios en blanco para hacerlo legible para los humanos. Un objeto JSON compacto como {"name":"John","age":30,"hobbies":["reading","coding"]} se convierte en una representación estructurada con sangría:

{
  "name": "John",
  "age": 30,
  "hobbies": [
    "reading",
    "coding"
  ]
}

El proceso no cambia los datos, solo su presentación visual. La mayoría de los formateadores ofrecen sangría configurable (2 espacios, 4 espacios o tabulaciones) y ordenación opcional de claves. Algunos también ofrecen resaltado de sintaxis, vistas de árbol colapsables y resaltado de errores para JSON inválido.

Método en Línea

La herramienta Help2Code JSON Formatter proporciona formato instantáneo con resaltado de sintaxis, validación y una vista de árbol. Es la forma más rápida de formatear JSON sin instalar ningún software. Simplemente pega tu cadena JSON en el área de entrada y la herramienta la formatea en tiempo real. Las características clave incluyen:

• Formateo en tiempo real mientras escribes o pegas
• Resaltado de sintaxis para claves, cadenas, números, booleanos y valores nulos
• Validación JSON con mensajes de error específicos por línea
• Vista de árbol colapsable para navegar estructuras profundamente anidadas
• Descargar la salida formateada como archivo
• Modo minificar para comprimir JSON formateado de vuelta a forma compacta
• Copiar al portapapeles con un clic

Esta herramienta es ideal para desarrolladores que necesitan inspeccionar rápidamente respuestas de API, depurar archivos de configuración o compartir JSON formateado con colegas.

Comparación de Métodos

DevTools del Navegador

Todos los navegadores modernos incluyen formateo JSON integrado en sus herramientas de desarrollo. Cuando registras objetos en la consola usando console.log(), el navegador los muestra automáticamente en una vista de árbol interactiva y colapsable. Sin embargo, para tener más control sobre el formato, usa JSON.stringify() con opciones de formato:

// In browser console
const data = {
  name: "John",
  age: 30,
  hobbies: ["reading", "coding"],
  address: {
    street: "123 Main St",
    city: "Boston",
    zip: "02101"
  }
};

// Pretty print with 2-space indentation
console.log(JSON.stringify(data, null, 2));

// Pretty print with 4-space indentation
console.log(JSON.stringify(data, null, 4));

// Pretty print with tab indentation
console.log(JSON.stringify(data, null, '\t'));

// Using console.table for arrays of objects
const users = [
  { id: 1, name: "Alice", role: "Admin" },
  { id: 2, name: "Bob", role: "User" }
];
console.table(users);

La pestaña Red (Network) de Chrome DevTools también incluye un visor JSON integrado para respuestas de API. Cuando una respuesta tiene Content-Type: application/json, la pestaña Vista Previa formatea y resalta automáticamente la sintaxis del cuerpo de la respuesta con secciones colapsables.

VS Code

Visual Studio Code proporciona excelente soporte de edición y formateo JSON listo para usar:

1. Formatear Documento: Selecciona contenido JSON y presiona Shift+Alt+F (Windows/Linux) o Shift+Option+F (Mac), o haz clic derecho y selecciona "Formatear Documento".
2. Autoformateo al guardar: Añade "editor.formatOnSave": true a tu settings.json para formatear automáticamente archivos JSON al guardar.
3. JSON con Comentarios (.jsonc): VS Code soporta archivos JSON que contienen comentarios, comúnmente usados para archivos de configuración como settings.json y launch.json.

Extensiones adicionales de VS Code para manejo de JSON incluyen:

• Prettier - Formateador de código que soporta JSON con opciones personalizables
• JSON Tools - Añade comandos de ordenación, minificación y formato
• Bracket Pair Colorizer - Colorea pares de corchetes coincidentes para JSON profundamente anidado

Línea de Comandos (jq)

jq es un potente procesador JSON de línea de comandos que maneja formateo, filtrado, transformación y consultas. Está disponible en todas las plataformas a través de gestores de paquetes y es la herramienta preferida para la manipulación de JSON en scripts:

# Basic formatting - pipe JSON to jq with the identity filter
echo '{"name":"test","value":123}' | jq .

# Colorized output (disabled by default in pipes)
echo '{"name":"test"}' | jq -C .

# Read from file and format
jq . file.json

# Save formatted output
jq . file.json > formatted.json

# Format with specific indentation (default is 2)
jq --indent 4 . file.json

# Minify JSON (remove all whitespace)
jq -c . file.json

# Sort object keys alphabetically
jq -S . file.json

# Extract and format a specific field
cat data.json | jq '.users' | jq .

# Pretty print and colorize in one command
cat messy.json | jq -C . | less -R

jq también puede combinarse con otras herramientas de línea de comandos para potentes pipelines de procesamiento de datos:

# Fetch API response and format it
curl https://api.example.com/users | jq .

# Format only the first N items
curl https://api.example.com/users | jq '.[:5]'

# Transform and format
cat data.json | jq '{name: .user.name, email: .user.email}'

Métodos por Lenguaje de Programación

Cada lenguaje de programación importante incluye formateo JSON integrado o basado en bibliotecas:

JavaScript:

const pretty = JSON.stringify(obj, null, 2); // 2-space indent
const compact = JSON.stringify(obj); // no whitespace

// With custom replacer function to filter/transform values
const filtered = JSON.stringify(obj, ['name', 'age'], 2);

// Custom replacer to redact sensitive fields
const redacted = JSON.stringify(obj, (key, value) => {
  if (key === 'password' || key === 'ssn') return '***';
  return value;
}, 2);

// Using util.inspect in Node.js for more control
const util = require('util');
console.log(util.inspect(obj, { colors: true, depth: null, sorted: true }));

Python:

import json

data = {"name": "John", "age": 30, "active": True}

# Basic pretty print with 2-space indent
pretty = json.dumps(data, indent=2)

# Sort keys alphabetically
pretty = json.dumps(data, indent=2, sort_keys=True)

# Ensure non-ASCII characters are preserved (not escaped)
pretty = json.dumps(data, indent=2, ensure_ascii=False)

# Custom separators for more compact output
compact = json.dumps(data, separators=(',', ':'))

# Pretty print directly to console
print(json.dumps(data, indent=2, sort_keys=True))

PHP:

$data = ["name" => "John", "age" => 30, "hobbies" => ["reading"]];

// Basic pretty print
$pretty = json_encode($data, JSON_PRETTY_PRINT);

// Preserve Unicode characters
$pretty = json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

// Sort keys
$pretty = json_encode($data, JSON_PRETTY_PRINT | JSON_SORT_KEYS);

// Format with escaping for HTML
$pretty = json_encode($data, JSON_PRETTY_PRINT | JSON_HEX_TAG | JSON_HEX_AMP);

Ruby:

require 'json'

data = { name: "John", age: 30, active: true }

# Pretty print
puts JSON.pretty_generate(data)

# Custom options
puts JSON.pretty_generate(data, indent: "    ")

Go:

package main

import (
    "encoding/json"
    "fmt"
)

func main() {
    data := map[string]interface{}{
        "name": "John",
        "age": 30,
    }
    pretty, _ := json.MarshalIndent(data, "", "  ")
    fmt.Println(string(pretty))
}

Validación JSON Durante el Formateo

La mayoría de las herramientas de formateo también validan la sintaxis JSON. El JSON inválido no puede formatearse porque el analizador no puede determinar la estructura prevista. Los errores comunes de validación JSON incluyen:

• Comas finales ([1, 2,]) - Aunque están permitidas en JavaScript, las comas finales son inválidas en JSON
• Comillas simples ('value') - JSON requiere comillas dobles para cadenas
• Comillas faltantes alrededor de claves ({name: "John"}) - Las claves deben estar entre comillas
• Caracteres de control sin escapar - Tabulación, nueva línea y retorno de carro deben escaparse como \t, \n, \r
• Comentarios - JSON no soporta comentarios; usa formato JSONC si se necesitan comentarios

Cuándo Usar Cada Método

Elegir el método correcto depende de tu flujo de trabajo:

• Formateo puntual: Herramienta en línea (más rápida, sin instalación)
• Durante el desarrollo: DevTools del navegador o VS Code (integrados en tu flujo de trabajo)
• En scripts y automatización: jq (compatible con pipelines, programable)
• Formateo programático en aplicaciones: Métodos específicos del lenguaje (JavaScript JSON.stringify, Python json.dumps, PHP json_encode)
• Archivos grandes: jq o herramientas de línea de comandos (eficientes en memoria para streaming)

Conclusión

Formatear JSON de forma legible es una habilidad fundamental para cualquier desarrollador que trabaje con APIs, archivos de configuración o procesamiento de datos. Con métodos disponibles para cada entorno — desde herramientas en línea hasta utilidades de línea de comandos y todos los lenguajes de programación importantes — siempre hay una forma de hacer tu JSON legible. La clave es elegir la herramienta adecuada para tu contexto: rápida y conveniente para inspecciones rápidas, potente y programable para pipelines automatizados.