JSONPath Complete Guide

What Is JSONPath?

JSONPath is a query expression language for extracting specific data from JSON documents, analogous to XPath for XML. JSONPath expressions let you locate any element in JSON using concise syntax — regardless of how deeply nested it is — without writing complex recursive code.

JSONPath was originally proposed by Stefan Goessner in 2007 and now has RFC 9535 standard (officially published in 2024) formalizing its syntax. It's widely used in various tools and systems: jq (command-line JSON processor), Kubernetes (resource config querying), Ansible (configuration management), various API testing frameworks, and more.

JSONPath Basic Syntax

JSONPath uses these basic symbols:

$ — 根节点（Root element）
. — 子元素访问符（Child accessor）
.. — 递归下降，搜索所有后代
* — 通配符，匹配所有子元素
[] — 下标操作符（数组索引、属性名、过滤器）
[n] — 访问数组第 n 个元素（0-based）
[*] — 数组所有元素
[start:end] — 数组切片
[?(...)] — 过滤器表达式

Practical Examples: Extracting Data from JSON

Given the following JSON data:

{
  "store": {
    "books": [
      {"title": "The Great Gatsby", "price": 12.99, "category": "fiction"},
      {"title": "Python Crash Course", "price": 29.99, "category": "tech"},
      {"title": "Clean Code", "price": 34.99, "category": "tech"}
    ],
    "owner": "Alice"
  }
}

Common JSONPath queries:

$.store.owner          → "Alice"
$.store.books[0].title → "The Great Gatsby"
$.store.books[*].price → [12.99, 29.99, 34.99]
$.store.books[-1].title → "Clean Code"（最后一本）
$..title               → 递归查找所有 title 字段
$.store.books[1:3]     → 第 2、3 本书（切片）

Filter Expressions: Conditional Queries

JSONPath's filter expression [?(...)] allows filtering array items by condition; @ represents the current element:

// 价格大于 20 的书
$.store.books[?(@.price > 20)]

// 分类为 tech 的书
$.store.books[?(@.category == 'tech')]

// 价格在 10-30 之间的书
$.store.books[?(@.price >= 10 && @.price <= 30)]

// 有特定字段的元素（字段存在性检查）
$.store.books[?(@.isbn)]

JSONPath-Style Querying in jq

jq has its own query syntax, similar to but not identical with JSONPath. Common jq query examples:

# 提取字段
jq '.store.owner' data.json

# 数组所有元素的字段
jq '.store.books[].title' data.json

# 过滤：价格 > 20
jq '.store.books[] | select(.price > 20)' data.json

# 提取特定字段并重构
jq '.store.books[] | {title, price}' data.json

# 聚合：计算总价
jq '[.store.books[].price] | add' data.json

Using JSONPath in JavaScript

JavaScript doesn't have built-in JSONPath support; third-party libraries are needed:

// 使用 jsonpath-plus 库
import jsonpath from 'jsonpath-plus';

const results = jsonpath.query(data, '$.store.books[?(@.price > 20)]');
console.log(results);

// 使用 @jsonpath/jsonpath-ts（TypeScript 友好）
import { JSONPath } from 'jsonpath-plus';
const titles = JSONPath({ path: '$..title', json: data });

Real-World JSONPath Applications

API Testing: In tools like Postman and Newman, use JSONPath expressions to extract specific values from responses for assertions, e.g., verify that $.data.user.id equals an expected value.

Kubernetes: The kubectl command supports JSONPath output format, e.g., kubectl get pods -o jsonpath='{.items[*].metadata.name}' extracts all Pod names.

Data extraction and transformation: In ETL (Extract-Transform-Load) workflows, use JSONPath to extract required fields from complex nested JSON and generate structured data.

Log analysis: Structured logs are typically recorded in JSON format; JSONPath queries can quickly extract specific fields from large volumes of logs for analysis.