Guía de consulta JSONPath: Extracción precisa de datos anidados de JSON

Qué es JSONPath

JSONPath es un lenguaje de consulta para JSON, similar a XPath para XML, que extrae datos con precisión de JSON anidado complejo:

{
  "store": {
    "books": [
      {"title": "The Three-Body Problem", "price": 68},
      {"title": "To Live", "price": 45},
      {"title": "One Hundred Years of Solitude", "price": 55}
    ]
  }
}

Usa $.store.books[*].title para extraer todos los títulos: ["The Three-Body Problem", "To Live", "One Hundred Years of Solitude"]

Referencia de sintaxis básica

Sintaxis	Significado	Ejemplo
`$`	Nodo raíz	`$`
`.`	Nodo hijo	`$.store`
`[]`	Índice de array o nodo hijo	`$[0]`, `$['key']`
`*`	Comodín, todos los elementos	`$.store.*`
`..`	Descenso recursivo, todos los niveles	`$..title`
`[start:end]`	Slice de array	`$[0:2]`
`[?(expr)]`	Expresión de filtro	`$[?(@.price > 50)]`

Sintaxis explicada en detalle

Nodo raíz $

$ representa la raíz del JSON. Todos los caminos comienzan desde $:

$           → Todo el JSON
$.store     → El objeto store

Acceso a nodos hijos .

Usa . o [] para acceder a nodos hijos:

$.store.books        → El array books
$.store['books']     → Forma equivalente; necesaria cuando los nombres de claves contienen caracteres especiales

Índice de array []

$.store.books[0]     → Primer libro
$.store.books[-1]    → Último libro
$.store.books[0:2]   → Primeros dos libros (slice)

Comodín *

$.store.books[*]           → Todos los libros
$.store.books[*].title     → Todos los títulos

Descenso recursivo ..

.. busca en todos los niveles sin necesitar la ruta completa:

$..title     → Todos los campos title en cualquier nivel
$..price     → Todos los campos price en cualquier nivel

.. es especialmente útil en respuestas de API profundamente anidadas.

Expresiones de filtro ?()

El filtrado es la característica más potente de JSONPath:

Operadores de comparación

Operador	Significado	Ejemplo
`==`	Igual a	`$[?(@.price == 45)]`
`!=`	Diferente de	`$[?(@.price != 45)]`
`>`	Mayor que	`$[?(@.price > 50)]`
`<`	Menor que	`$[?(@.price < 50)]`
`>=`	Mayor o igual que	`$[?(@.price >= 55)]`

Operadores lógicos

$[?(@.price > 50 && @.price < 70)]    → Precio entre 50 y 70
$[?(@.category == 'fiction' || @.price < 40)]    → Ficción o precio menor a 40

Coincidencia de cadenas

$[?(@.title =~ /Three.*/)]    → Título que comienza con "Three"

Uso de la herramienta JSONPath

Paso 1: Abrir la herramienta

Visita la herramienta JSONPath para entrar a la interfaz de consulta.

Paso 2: Ingresar datos JSON

Pega tu respuesta de API o datos JSON en el cuadro de entrada. Puedes embellecerlos primero con el Formateador JSON.

Paso 3: Escribir una expresión JSONPath

Ingresa una expresión en el cuadro de consulta, ej. $.data.users[*].name.

Paso 4: Ver los resultados de extracción

La herramienta muestra los resultados coincidentes en tiempo real y resalta los nodos coincidentes en el origen.

Práctica: Extracción de datos de respuestas de API

Ejemplo de API de GitHub

{
  "items": [
    {"full_name": "vuejs/vue", "stargazers_count": 45000, "language": "TypeScript"},
    {"full_name": "facebook/react", "stargazers_count": 42000, "language": "JavaScript"}
  ]
}

$.items[*].full_name              → Todos los nombres de repositorios
$.items[?(@.stargazers_count > 43000)].full_name  → Nombres de repos con Stars > 43000

Extracción de datos paginados

$.data.list[*].id                 → Todos los IDs en la página actual
$.pagination.next_cursor          → Cursor de la siguiente página

JSONPath vs JMESPath

Comparación	JSONPath	JMESPath
Estilo de sintaxis	Similar a XPath	Similar a SQL/pipes
Búsqueda recursiva	`..` soportado nativamente	Requiere recorrido explícito
Sintaxis de filtro	`[?(@.x > 1)]`	`[?x >` 1`]`
Proyección/transformación	No soportado	Soporta `[*].{n: name}`
Ordenamiento de múltiples resultados	No garantizado	Puede ordenar
Herramienta	JSONPath	JMESPath

Usa JSONPath para extracción simple, JMESPath para transformación/proyección.

Problemas comunes

Problema	Causa	Solución
La consulta devuelve vacío	Error tipográfico en la ruta	Verificar mayúsculas/minúsculas de los nombres de claves
El filtro no funciona	Diferencia en la versión de sintaxis	Confirmar la versión de sintaxis soportada por la herramienta
Índice de array fuera de rango	El índice excede el rango	Usar `[*]` o verificar la longitud del array
Demasiados resultados recursivos	`..` coincidió en todos los niveles	Reducir el alcance o añadir condiciones de filtro
Error en clave con caracteres especiales	La clave contiene `.` o `-`	Usar sintaxis de corchetes `['key.name']`

Resumen

JSONPath es una herramienta potente para trabajar con datos JSON. Domina los seis elementos de sintaxis principales — $, ., [], *, .., ?() — y podrás extraer datos con precisión de cualquier JSON anidado. La herramienta JSONPath proporciona consultas en tiempo real con posicionamiento resaltado, mientras que JMESPath y el Formateador JSON completan tu flujo de trabajo de procesamiento de datos JSON.