Buscador de Rutas JSON: Guía Completa de JSONPath y jq

# Buscador de Rutas JSON: Guía Completa de JSONPath y jq

Navegar estructuras JSON complejas puede ser desafiante. Esta guía completa te enseñará cómo usar JSONPath y jq para consultar y extraer datos JSON eficientemente.

¿Qué es JSONPath?

JSONPath es un lenguaje de consulta para JSON, similar a XPath para XML. Permite navegar y extraer datos de estructuras JSON complejas usando expresiones de ruta.

Sintaxis Básica

$           - Nodo raíz
.           - Operador de hijo
..          - Búsqueda recursiva
           - Comodín (cualquier elemento)
[]          - Operador de subíndice
[,]         - Operador de unión
[start:end] - Operador de slice
?()         - Filtro de predicado

{
  "tienda": {
    "nombre": "TechStore",
    "libros": [
      {
        "categoria": "programacion",
        "autor": "Robert Martin",
        "titulo": "Clean Code",
        "precio": 32.50,
        "isbn": "978-0132350884"
      },
      {
        "categoria": "programacion",
        "autor": "Martin Fowler",
        "titulo": "Refactoring",
        "precio": 44.99,
        "isbn": "978-0201485677"
      },
      {
        "categoria": "ficcion",
        "autor": "J.K. Rowling",
        "titulo": "Harry Potter",
        "precio": 15.99,
        "isbn": "978-0439708180"
      }
    ],
    "bicicleta": {
      "color": "rojo",
      "precio": 299.99
    }
  }
}

// Todos los autores
$.tienda.libros[].autor
// Resultado: ["Robert Martin", "Martin Fowler", "J.K. Rowling"]

// Primer libro
$.tienda.libros[0]
// Resultado: {categoria: "programacion", autor: "Robert Martin", ...}

// Últimos dos libros
$.tienda.libros[-2:]
// Resultado: [libro2, libro3]

// Todos los precios
$.tienda..precio
// Resultado: [32.50, 44.99, 15.99, 299.99]

// Títulos de todos los libros
$.tienda.libros[].titulo

// Resultado: ["Clean Code", "Refactoring", "Harry Potter"]

// Libros con precio < 20
$.tienda.libros[?(@.precio < 20)]
// Resultado: [Harry Potter]

// Libros de categoría programacion
$.tienda.libros[?(@.categoria == 'programacion')]
// Resultado: [Clean Code, Refactoring]

// Libros con precio entre 30 y 50
$.tienda.libros[?(@.precio >= 30 && @.precio <= 50)]
// Resultado: [Clean Code, Refactoring]

// Libros cuyo autor contiene "Martin"
$.tienda.libros[?(@.autor =~ /.Martin./i)]

// Resultado: [Clean Code, Refactoring]

npm install jsonpath

const jp = require('jsonpath');

const datos = {
  usuarios: [
    { id: 1, nombre: "Ana", edad: 28, ciudad: "Madrid" },
    { id: 2, nombre: "Carlos", edad: 35, ciudad: "Barcelona" },
    { id: 3, nombre: "María", edad: 31, ciudad: "Madrid" }
  ]
};

// Consulta básica
const nombres = jp.query(datos, '$.usuarios[].nombre');
console.log(nombres);
// ["Ana", "Carlos", "María"]

// Con filtro
const madrilenos = jp.query(datos, '$.usuarios[?(@.ciudad == "Madrid")]');
console.log(madrilenos);
// [{id: 1, ...}, {id: 3, ...}]

// Mayores de 30
const mayores = jp.query(datos, '$.usuarios[?(@.edad > 30)]');
console.log(mayores);
// [{id: 2, ...}, {id: 3, ...}]

// Obtener rutas
const rutas = jp.paths(datos, '$.usuarios[].nombre');

console.log(rutas);
// [['$', 'usuarios', 0, 'nombre'], ['$', 'usuarios', 1, 'nombre'], ...]

// Obtener nodos con sus rutas
const nodos = jp.nodes(datos, '$.usuarios[].edad');
console.log(nodos);
// [{path: ['$', 'usuarios', 0, 'edad'], value: 28}, ...]

Modificar Valores

const jp = require('jsonpath');

const datos = {
  productos: [
    { nombre: "Laptop", precio: 999 },
    { nombre: "Mouse", precio: 29 },
    { nombre: "Teclado", precio: 79 }
  ]
};

// Aplicar descuento del 10%
jp.apply(datos, '$.productos[].precio', (precio) => precio  0.9);

console.log(datos.productos);
// Todos los precios reducidos en 10%

// Actualizar precio específico
jp.value(datos, '$.productos[0].precio', 899);

// Añadir propiedad a todos
jp.apply(datos, '$.productos[]', (producto) => {

  producto.disponible = true;
  return producto;
});

pip install jsonpath-ng

from jsonpath_ng import jsonpath, parse

datos = {
    "empresa": {
        "empleados": [
            {"nombre": "Ana", "departamento": "IT", "salario": 60000},
            {"nombre": "Carlos", "departamento": "Ventas", "salario": 55000},
            {"nombre": "María", "departamento": "IT", "salario": 65000}
        ]
    }
}

# Parsear expresión JSONPath
expr = parse('$.empresa.empleados[].nombre')

# Encontrar coincidencias
matches = [match.value for match in expr.find(datos)]
print(matches)
# ['Ana', 'Carlos', 'María']

# Con filtro (requiere jsonpath-ng extensión)
from jsonpath_ng.ext import parse

# Empleados de IT
expr = parse('$.empresa.empleados[?(@.departamento == "IT")]')
it_empleados = [match.value for match in expr.find(datos)]
print(it_empleados)

# Salarios mayores a 60000
expr = parse('$.empresa.empleados[?(@.salario > 60000)]')
altos_salarios = [match.value for match in expr.find(datos)]
print(altos_salarios)

Actualizar Valores

from jsonpath_ng.ext import parse

datos = {
    "productos": [
        {"id": 1, "precio": 100},
        {"id": 2, "precio": 200}
    ]
}

# Parsear expresión
expr = parse('$.productos[].precio')


# Actualizar valores
for match in expr.find(datos):
    match.full_path.update(datos, match.value  1.1)  # Incrementar 10%

print(datos)

jq - Procesador JSON de Línea de Comandos

Instalación

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Windows (Chocolatey)
choco install jq

# Windows (Scoop)
scoop install jq

Sintaxis Básica de jq

# Identidad (formatear)
echo '{"nombre":"Ana"}' | jq .

# Acceder a propiedad
echo '{"nombre":"Ana","edad":28}' | jq '.nombre'
# "Ana"

# Acceder a elemento de array
echo '[1,2,3,4,5]' | jq '.[2]'
# 3

# Slice de array
echo '[1,2,3,4,5]' | jq '.[1:3]'
# [2,3]

Consultas con jq

# Archivo: usuarios.json
cat usuarios.json | jq .

# Extraer todos los nombres
jq '.usuarios[].nombre' usuarios.json

# Primer usuario
jq '.usuarios[0]' usuarios.json

# Últimos dos usuarios
jq '.usuarios[-2:]' usuarios.json

# Todos los nombres en un array
jq '[.usuarios[].nombre]' usuarios.json

# Contar elementos
jq '.usuarios | length' usuarios.json

Filtros en jq

# Usuarios mayores de 30
jq '.usuarios[] | select(.edad > 30)' usuarios.json

# Usuarios de Madrid
jq '.usuarios[] | select(.ciudad == "Madrid")' usuarios.json

# Usuarios cuyo nombre contiene "Ana"
jq '.usuarios[] | select(.nombre | contains("Ana"))' usuarios.json

# Múltiples condiciones
jq '.usuarios[] | select(.edad > 25 and .ciudad == "Madrid")' usuarios.json

# Negación
jq '.usuarios[] | select(.activo != false)' usuarios.json

Transformaciones con jq

# Crear nuevo objeto
jq '.usuarios[] | {nombre: .nombre, info: .ciudad}' usuarios.json

# Mapear array
jq '.usuarios | map({nombre, edad})' usuarios.json

# Añadir campo
jq '.usuarios[] | . + {pais: "España"}' usuarios.json

# Ordenar por campo
jq '.usuarios | sort_by(.edad)' usuarios.json

# Ordenar descendente
jq '.usuarios | sort_by(.edad) | reverse' usuarios.json

# Agrupar por campo
jq 'group_by(.ciudad)' usuarios.json

# Valores únicos
jq '.usuarios | map(.ciudad) | unique' usuarios.json

Agregaciones con jq

# Suma de edades
jq '.usuarios | map(.edad) | add' usuarios.json

# Promedio
jq '.usuarios | map(.edad) | add / length' usuarios.json

# Máximo
jq '.usuarios | map(.edad) | max' usuarios.json

# Mínimo
jq '.usuarios | map(.edad) | min' usuarios.json

# Contar por condición
jq '[.usuarios[] | select(.edad > 30)] | length' usuarios.json

Operaciones Avanzadas

# Búsqueda recursiva
jq '.. | .precio? // empty' datos.json

# Todas las claves
jq 'keys' datos.json

# Claves recursivas
jq '[.. | keys?] | add | unique' datos.json

# Convertir array a objeto
jq '.usuarios | map({(.nombre): .edad}) | add' usuarios.json

# Flatten array anidado
jq '.datos | flatten' datos.json

# Eliminar claves
jq 'del(.password)' usuario.json

Ejemplos Prácticos

Extraer Datos de API

# Obtener nombres de repositorios GitHub
curl -s https://api.github.com/users/username/repos |   jq '.[].name'

# Repos con más de 10 stars
curl -s https://api.github.com/users/username/repos |   jq '.[] | select(.stargazers_count > 10) | {nombre: .name, stars: .stargazers_count}'

Procesar Logs

# Filtrar errores
jq 'select(.level == "error")' logs.json

# Contar por nivel
jq 'group_by(.level) | map({nivel: .[0].level, count: length})' logs.json

# Errores de las últimas 24 horas
jq --arg fecha "$(date -d '24 hours ago' -u +%Y-%m-%dT%H:%M:%S)"   'select(.timestamp > $fecha and .level == "error")' logs.json

Transformar Datos

# CSV a JSON
jq -R -s '
  split("
") | 
  map(split(",")) | 
  .[1:] | 
  map({nombre: .[0], edad: .[1], ciudad: .[2]})
' datos.csv

# JSON a CSV
jq -r '.usuarios[] | [.nombre, .edad, .ciudad] | @csv' usuarios.json

Combinar Múltiples Archivos

# Merge dos archivos JSON
jq -s '.[0]  .[1]' archivo1.json archivo2.json


# Combinar arrays
jq -s 'add' archivo1.json archivo2.json

# Merge profundo
jq -s 'reduce .[] as $item ({}; .  $item)' *.json

Herramientas Online

Big JSON Viewer

✓ Vista de árbol navegable
✓ Copiar JSONPath con un click
✓ Búsqueda por ruta
✓ Maneja archivos grandes
✓ Sin necesidad de instalar nada

JSONPath Online Evaluator

• Probar expresiones JSONPath
• Ver resultados en tiempo real
• Ejemplos interactivos

Mejores Prácticas

1. Usa Expresiones Específicas

# ✅ Bueno - Específico
jq '.usuarios[] | select(.id == 123)'

# ❌ Malo - Demasiado general
jq '.. | select(.id == 123)'

2. Combina Filtros Eficientemente

# ✅ Bueno - Filtro combinado
jq '.usuarios[] | select(.edad > 30 and .ciudad == "Madrid")'

# ❌ Malo - Múltiples pipes innecesarios
jq '.usuarios[] | select(.edad > 30) | select(.ciudad == "Madrid")'

3. Usa Variables en jq

# Definir variables
jq --arg min "30" --arg ciudad "Madrid"   '.usuarios[] | select(.edad > ($min | tonumber) and .ciudad == $ciudad)'   usuarios.json

4. Maneja Valores Nulos

# Proporcionar valor por defecto
jq '.usuario.email // "sin-email"' datos.json

# Filtrar nulls
jq '.datos[] | select(. != null)' datos.json

5. Optimiza para Archivos Grandes

# Stream procesando (más eficiente en memoria)
jq -c '.usuarios[]' usuarios_grandes.json

# Procesar en fragmentos
jq -c '.usuarios[] | select(.activo)' usuarios_grandes.json |   while read linea; do
    echo "$linea" | jq .
  done

Scripts Útiles

Script de Búsqueda JSON

#!/bin/bash
# buscar_json.sh

if [ $# -lt 2 ]; then
  echo "Uso: $0 <archivo.json> <clave> [valor]"
  exit 1
fi

archivo=$1
clave=$2
valor=$3

if [ -z "$valor" ]; then
  # Buscar todas las ocurrencias de la clave
  jq -r ".. | select(type == "object") | select(has("$clave")) | .$clave" "$archivo"
else
  # Buscar donde clave == valor
  jq -r ".. | select(type == "object") | select(has("$clave") and .$clave == "$valor")" "$archivo"
fi

Script de Extracción

#!/bin/bash
# extraer.sh

# Extraer campos específicos de JSON
archivo=$1
shift
campos="$@"

expresion="{"
primera=true
for campo in $campos; do
  if [ "$primera" = true ]; then
    expresion="$expresion$campo"
    primera=false
  else
    expresion="$expresion, $campo"
  fi
done
expresion="$expresion}"

jq ".[] | $expresion" "$archivo"

Casos de Uso Avanzados

Analizar Estructura JSON

# Ver todas las claves únicas en JSON
jq '[paths(scalars) | join(".")] | unique' datos.json

# Contar profundidad de anidación
jq '[paths | length] | max' datos.json

# Tipos de datos de cada campo
jq 'paths(scalars) as $p | {($p | join(".")): (getpath($p) | type)}' datos.json

Validar Datos

# Verificar que todos los usuarios tienen email
jq '.usuarios[] | select(.email == null or .email == "") | .nombre' usuarios.json

# Encontrar duplicados
jq '.usuarios | group_by(.email) | map(select(length > 1))' usuarios.json

Conclusión

JSONPath y jq son herramientas esenciales para trabajar con datos JSON complejos. Dominar estas herramientas te permite consultar, filtrar y transformar datos JSON eficientemente.

Puntos Clave

• JSONPath proporciona sintaxis de consulta similar a XPath
• jq es extremadamente potente para procesamiento en línea de comandos
• Big JSON Viewer facilita la navegación visual de JSON
• Combina herramientas según tus necesidades

¡Comienza a dominar JSONPath y jq para trabajar con JSON como un profesional!