Tutorial de jq: filtra y transforma JSON

jq es la herramienta estándar de línea de comandos para cortar, filtrar y transformar JSON. Convierte one-liners en un potente lenguaje de consulta para respuestas de API, archivos de log y configuración. Este tutorial cubre la instalación, los filtros principales que usarás cada día, y un conjunto de recetas para copiar y pegar para las tareas más comunes del mundo real.

¿Qué es jq?

jq lee JSON de un archivo o de la entrada estándar, aplica un filter, y escribe JSON (o texto raw) en la salida estándar. Lo formatea por defecto y nunca envía tus datos a ningún sitio —— es un binario local, ideal para payloads sensibles.

Instalar jq

# macOS
brew install jq

# Debian / Ubuntu
sudo apt-get install jq

# Windows (winget o choco)
winget install jqlang.jq

# Verifica
jq --version

El filtro identity: formatear cualquier cosa

El filtro más simple, ., devuelve la entrada sin cambios —— lo que hace de jq un formateador instantáneo:

# Formatear un archivo
jq . data.json

# Formatear una respuesta curl
curl -s https://api.example.com/users | jq .

# Al revés: minify (salida compacta)
jq -c . data.json

Seleccionar campos

Entra en objetos con .key, y en arrays con []:

echo '{"user":{"name":"Ada","age":36}}' | jq '.user.name'
# "Ada"

# Todos los elementos de un array
echo '[{"id":1},{"id":2}]' | jq '.[]'
# {"id":1}
# {"id":2}

# Un campo de cada elemento del array
echo '[{"id":1,"name":"Ada"},{"id":2,"name":"Bob"}]' | jq '.[].name'
# "Ada"
# "Bob"

# Quita las comillas de JSON con -r (raw output)
jq -r '.[].name' users.json

Filtrar con select

# Mantén solo los objetos que cumplen una condición
echo '[{"name":"Ada","active":true},{"name":"Bob","active":false}]' \
  | jq '.[] | select(.active == true)'
# {"name":"Ada","active":true}

# Comparación numérica
jq '.[] | select(.age > 30)' users.json

Transformar con map y construcción de objetos

# Reformula cada elemento en un objeto nuevo
echo '[{"id":1,"name":"Ada","email":"a@x.com"}]' \
  | jq 'map({ userId: .id, label: .name })'
# [{"userId":1,"label":"Ada"}]

# Saca una lista plana de valores
jq '[.[].email]' users.json     # ["a@x.com", ...]

# Encadena filtros con |
jq '.items | map(.price) | add' order.json   # suma de todos los precios

Recetas comunes

Remodelar objetos: to_entries / from_entries

Los dos transformadores de forma de objeto más útiles de jq:

# Renombra cada key (aquí a minúsculas)
echo '{"Name":"Ada","Active":true}' \
  | jq 'with_entries(.key |= ascii_downcase)'
# → {"name":"Ada","active":true}

# Elimina keys cuyo valor sea null
jq 'with_entries(select(.value != null))' file.json

# Objeto ⇄ array de pares
jq 'to_entries' file.json     # → [{"key":"name","value":"Ada"}, ...]
jq 'from_entries' pairs.json  # → {"name":"Ada", ...}

Interpolación y formatos de salida: \(.x), @csv, @json, @base64

jq tiene interpolación de strings y format strings incorporados para convertir JSON en otros formatos:

# Interpolación de strings dentro de un string entre comillas
jq -r '"\(.user) bought \(.items|length) items"' order.json

# Una fila CSV por objeto
jq -r '.[] | [.id, .name, .total] | @csv' orders.json

# JSON inline para shells (literal de string escapado)
jq -r '.user | @json' record.json

# Codifica un valor en Base64 (útil para tokens / data URIs)
jq -r '.payload | @base64' message.json
# Lado de decodificación: jq acepta @base64d en versiones más nuevas

Validar JSON con jq

Como jq sale con código distinto de cero con entrada inválida, jq empty file.json es un chequeo de validez limpio para scripts y CI —— ve Cómo validar JSON para más enfoques de validación.

Cuándo una herramienta del navegador es más rápida

jq brilla en scripts y pipelines, pero para algo puntual —— formatear una respuesta pegada, inspeccionar una estructura desconocida o reparar JSON roto —— una herramienta del navegador no necesita instalación ni escapado de shell:

• JSON Fix —— formatea y repara JSON en un paso
• JSON Viewer —— explora respuestas grandes como un árbol colapsable
• Cómo formatear JSON —— formateo en código y línea de comandos

Preguntas frecuentes

¿Cómo formateo JSON con jq?

Ejecuta jq . file.json —— el filtro identity . devuelve la entrada y jq la formatea por defecto. Usa -c para salida compacta.

¿Cómo extraigo un solo campo con jq?

Usa un filtro de ruta como jq '.data.token', y añade -r para salida raw si quieres el valor sin las comillas.

¿Cómo filtro un array JSON con jq?

Itera con .[] y aplica select(), p. ej. jq '.[] | select(.active == true)'.

¿Puede jq validar JSON?

Sí —— jq empty file.json parsea la entrada y sale con código distinto de cero si es inválida, lo que lo hace útil en CI. Para más detalles ve Cómo validar JSON.

Sigue leyendo

• Cómo formatear JSON —— jq, JavaScript, Python y formateo en el navegador
• Cómo minificar JSON —— salida compacta con jq -c y más allá
• Cómo validar JSON —— incluyendo jq empty en CI
• JSON Viewer —— alternativa en el navegador para explorar JSON