Guía de Consultas JSONPath: Extrayendo Datos Como un Profesional

JSONPath es un lenguaje de consulta para JSON, similar a cómo XPath funciona para XML. Cuando estás trabajando con respuestas JSON complejas y profundamente anidadas de APIs, JSONPath te permite extraer exactamente los datos que necesitas sin escribir bucles y condicionales. Esta guía cubre la sintaxis, los operadores y los patrones del mundo real que necesitas.

¿Por Qué JSONPath?

Considera una respuesta típica de API con datos anidados:

{
  "store": {
    "books": [
      { "title": "Clean Code", "author": "Robert Martin", "price": 32.99, "tags": ["programming", "best-practices"] },
      { "title": "Design Patterns", "author": "Gang of Four", "price": 44.99, "tags": ["programming", "architecture"] },
      { "title": "The Pragmatic Programmer", "author": "Hunt & Thomas", "price": 39.99, "tags": ["programming", "career"] }
    ],
    "music": [
      { "title": "Kind of Blue", "artist": "Miles Davis", "price": 12.99 }
    ]
  }
}

Para obtener todos los títulos de libros, podrías escribir un bucle — o usar JSONPath: $.store.books[*].title

Sintaxis Básica

Notación de Punto vs Notación de Corchetes

Ambas notaciones acceden a propiedades, pero la notación de corchetes es necesaria para caracteres especiales:

# Notación de punto
$.store.books[0].title

# Notación de corchetes (equivalente)
$['store']['books'][0]['title']

# Requerida para claves con caracteres especiales
$['store']['price-range']

Operaciones con Arrays

Indexación

$.store.books[0]          # Primer libro
$.store.books[-1]         # Último libro
$.store.books[0,2]        # Primer y tercer libro

Segmentación

$.store.books[0:2]        # Primeros dos libros (índice 0 y 1)
$.store.books[1:]         # Todos los libros excepto el primero
$.store.books[:2]         # Primeros dos libros
$.store.books[::2]        # Un libro de cada dos

Comodines

$.store.books[*].title    # Todos los títulos de libros
$.store.*                 # Todas las colecciones de la tienda (books, music)
$..title                  # Todos los títulos a cualquier profundidad
$..price                  # Todos los precios a cualquier profundidad

El operador de descenso recursivo (..) es particularmente poderoso para extraer valores independientemente de su posición en la jerarquía.

Expresiones de Filtro

Los filtros seleccionan elementos basados en condiciones:

# Libros más baratos que $40
$.store.books[?(@.price < 40)]

# Libros de un autor específico
$.store.books[?(@.author == 'Robert Martin')]

# Libros con más de 2 tags
$.store.books[?(@.tags.length > 2)]

# Libros que tienen una propiedad 'price'
$.store.books[?(@.price)]

Combinando Filtros

# Libros bajo $40 con tag de programming
$.store.books[?(@.price < 40 && @.tags[0] == 'programming')]

Ejemplos del Mundo Real

Extrayendo de Respuestas de API

GitHub API — obtener todos los nombres de repositorios:

$[*].name

Weather API — obtener la temperatura de hoy:

$.daily[0].temp.day

E-commerce API — obtener todas las imágenes de productos:

$.products[*].images[0].url

Extracción de Configuración

Docker Compose — obtener todos los nombres de servicios:

$.services.*~

Package.json — obtener todos los nombres de dependencias:

$.dependencies.*~

JSONPath vs jq

JSONPath y jq son ambas herramientas de consulta JSON, pero sirven en diferentes contextos:

Para procesamiento JSON en línea de comandos, jq es más poderoso. Para integrar consultas en aplicaciones o usar en herramientas web, JSONPath tiene soporte más amplio.

Prueba expresiones JSONPath interactivamente con nuestro Explorador JSON Path. Pega tu JSON, escribe una consulta y ve los resultados al instante.

Ejemplos de Implementación

JavaScript (jsonpath-plus)

const { JSONPath } = require('jsonpath-plus');
const result = JSONPath({
  path: '$.store.books[?(@.price < 40)].title',
  json: data
});
// ["Clean Code", "The Pragmatic Programmer"]

Python (jsonpath-ng)

from jsonpath_ng import parse
expr = parse('$.store.books[*].title')
titles = [match.value for match in expr.find(data)]

RFC 9535: El Estándar JSONPath

En febrero de 2024, JSONPath fue oficialmente estandarizado como RFC 9535. Esto aborda inconsistencias históricas entre implementaciones. Comportamientos estandarizados clave:

• Los índices de array están basados en 0
• Las expresiones de filtro usan @ para el elemento actual
• La comparación de cadenas distingue entre mayúsculas y minúsculas
• El resultado siempre es un array de valores coincidentes

Si estás eligiendo una biblioteca JSONPath, prefiere una que soporte RFC 9535 para un comportamiento consistente.

FAQ

¿Cuál es la diferencia entre JSONPath y JSON Pointer?

JSONPath es un lenguaje de consulta que puede coincidir con múltiples valores usando comodines y filtros. JSON Pointer (RFC 6901) es una sintaxis de ruta simple que apunta a exactamente un valor: /store/books/0/title. Usa JSONPath cuando necesites buscar o filtrar; usa JSON Pointer cuando conozcas la ruta exacta.

¿Puede JSONPath modificar datos JSON?

El JSONPath estándar es de solo lectura — extrae pero no modifica datos. Algunas bibliotecas extienden JSONPath con operaciones de set/delete, pero estas no son estándar. Para transformaciones, considera jq (línea de comandos) o escribe código de aplicación. Para ver y explorar la estructura JSON, nuestro Formateador JSON te ayuda a entender los datos antes de escribir consultas.

Recursos Relacionados

• Explorador JSON Path — Prueba expresiones JSONPath en tu navegador
• Mejores Prácticas de Formateo JSON — Estructura tu JSON para consultas más fáciles
• Guía de Validación con JSON Schema — Valida la estructura que tus consultas JSONPath esperan