JSONPath Query Guide: How to Search JSON Data

JSON has become the universal language of the web. APIs return JSON, configuration files use JSON, and databases store JSON documents. But as JSON structures grow larger and more deeply nested, finding specific values becomes increasingly difficult. That is where JSONPath comes in. JSONPath is a query language that lets you navigate and extract data from JSON documents using concise path expressions, much like XPath does for XML. This guide covers everything from basic syntax to advanced filtering, with practical examples you can apply immediately.

What Is JSONPath?

JSONPath is a query language for JSON that was originally proposed by Stefan Goessner in 2007. It provides a compact syntax for selecting nodes from a JSON document, similar to how CSS selectors target HTML elements or XPath expressions locate XML nodes. Instead of writing loops and conditional logic to traverse a JSON structure, you write a single expression that describes the path to the data you want.

JSONPath expressions start from the root of the JSON document and navigate through objects and arrays to reach the desired values. The language supports wildcards, recursive descent, array slicing, and filter expressions, making it powerful enough for most data extraction needs.

The Sample JSON Document

Throughout this guide, we will use the following JSON document as our working example. This is the classic example from the original JSONPath proposal, adapted with additional data:

{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      {
        "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      {
        "category": "fiction",
        "author": "J.R.R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  }
}

JSONPath Syntax Reference

JSONPath uses a small set of operators that combine to form powerful queries. Here is the complete syntax reference:

Basic JSONPath Expressions

Accessing the Root and Direct Children

The dollar sign $ represents the root of the JSON document. From there, you navigate using dot notation for object properties and bracket notation for array indices.

Bracket Notation

Bracket notation is an alternative to dot notation that is useful when property names contain special characters, spaces, or start with numbers:

$.store['book'][0]['title']
$['store']['bicycle']['color']

Bracket notation and dot notation are interchangeable for object properties. However, bracket notation is required when the property name is dynamic or contains characters that are not valid in dot notation.

Wildcard Operator

The wildcard operator * matches all elements in an array or all properties in an object. It is incredibly useful for extracting all values at a certain level without knowing the specific keys or indices.

Recursive Descent: The Double Dot Operator

The double dot operator .. is one of the most powerful JSONPath features. It searches for the specified key at every level of the JSON tree, not just the immediate children. Think of it as a deep search through the entire document.

The recursive descent operator is particularly useful when you do not know the exact path to the data you need, or when the same key appears at multiple levels of nesting. For example, if an API response contains id fields at various nesting levels, $..id collects them all.

Array Slicing

Array slicing lets you select a range of elements from an array. The syntax [start:end] selects elements from the start index up to (but not including) the end index. Both positive and negative indices are supported.

Note that slice behavior can vary slightly between JSONPath implementations. The syntax above follows the conventions used by most popular libraries and the IETF RFC 9535 standard.

Filter Expressions

Filter expressions are where JSONPath becomes truly powerful. They let you select elements based on conditions rather than positions. The filter syntax uses [?(condition)], where the condition is evaluated for each element.

Comparison Operators

JSONPath supports the following comparison operators in filter expressions:

Practical Filter Examples

Using our sample document, here are practical filter expressions and their results:

Find all books cheaper than $10:

$.store.book[?(@.price < 10)]

Returns the books "Sayings of the Century" ($8.95) and "Moby Dick" ($8.99).

Find all fiction books:

$.store.book[?(@.category == "fiction")]

Returns three books: "Sword of Honour", "Moby Dick", and "The Lord of the Rings".

Find books with an ISBN:

$.store.book[?(@.isbn)]

Returns books that have an isbn property: "Moby Dick" and "The Lord of the Rings". This works because the filter checks for the existence of the property.

Find the most expensive book:

$.store.book[?(@.price > 20)]

Returns "The Lord of the Rings" ($22.99).

Logical Operators in Filters

You can combine conditions using logical operators:

$.store.book[?(@.price < 10 && @.category == "fiction")]
$.store.book[?(@.price > 15 || @.category == "reference")]

The first expression finds fiction books under $10 (only "Moby Dick"). The second finds books that are either over $15 or in the reference category (returns "Sayings of the Century" and "The Lord of the Rings").

JSONPath vs XPath

JSONPath was explicitly modeled after XPath, and the two languages share many conceptual similarities. Understanding the relationship helps if you are familiar with XML processing.

The key difference is that XPath operates on a rich tree model with elements, attributes, text nodes, namespaces, and processing instructions. JSONPath operates on a simpler model of objects (key-value maps) and arrays (ordered lists). This simplicity makes JSONPath easier to learn but less expressive than XPath for complex queries.

JSONPath in Practice

API Testing

JSONPath is indispensable for API testing. When you send a request to an API and receive a large JSON response, JSONPath lets you assert specific values without navigating the entire structure manually. Most API testing tools support JSONPath natively.

For example, in a test you might verify that the first book's price is less than $10:

// Using a JSONPath assertion in testing
response.jsonPath().get("store.book[0].price").should(equals(8.95));

// Find all books by a specific author
response.jsonPath().get("store.book[?(@.author == 'Herman Melville')].title");
// Returns: ["Moby Dick"]

Data Transformation

When integrating systems that use different data formats, JSONPath helps extract and transform specific fields. You can pull values from one JSON structure and map them to another without writing complex traversal code.

Configuration Management

Complex configuration files often contain deeply nested JSON. JSONPath lets you query specific configuration values without loading and parsing the entire structure. Tools like jq use JSONPath-like syntax for processing JSON in command-line pipelines.

Monitoring and Alerting

In observability systems, JSONPath queries can extract metrics from JSON-formatted logs and API responses. You can set up alerts that trigger when a JSONPath query returns values exceeding thresholds.

JSONPath Implementations

JSONPath is available in virtually every programming language. Here are the most popular libraries:

JavaScript Example

import { JSONPath } from 'jsonpath-plus';

const data = { /* our sample JSON */ };

const authors = JSONPath({ path: '$..author', json: data });
// ["Nigel Rees", "Evelyn Waugh", "Herman Melville", "J.R.R. Tolkien"]

const cheapBooks = JSONPath({
  path: '$.store.book[?(@.price < 10)]',
  json: data
});
// Returns books with price < 10

Python Example

from jsonpath_ng import parse

data = { /* our sample JSON */ }

# Find all authors
author_expr = parse('$..author')
authors = [match.value for match in author_expr.find(data)]
# ["Nigel Rees", "Evelyn Waugh", "Herman Melville", "J.R.R. Tolkien"]

# Find cheap books
cheap_expr = parse('$.store.book[?(@.price < 10)]')
cheap_books = [match.value for match in cheap_expr.find(data)]

Common Pitfalls and Tips

• Zero-based vs one-based indexing: JSONPath uses zero-based indexing (the first element is [0]), while XPath uses one-based indexing (the first element is [1]). This is a common source of off-by-one errors.
• Implementation differences: Before the IETF standard (RFC 9535), JSONPath implementations varied in their handling of edge cases like empty results, null values, and filter syntax. Always test your expressions with the specific library you are using.
• Filter performance: Recursive descent with filters ($..book[?(@.price < 10)]) can be slow on large documents because it must traverse the entire tree. For performance-critical applications, use more specific paths when possible.
• Case sensitivity: JSONPath is case-sensitive. $.Store will not match $.store. This is consistent with JSON's case-sensitive nature.
• Escaping special characters: If a key name contains dots or brackets, you must use bracket notation with quotes: $['key.with.dots'] instead of $.key.with.dots.
• No parent traversal: Unlike XPath, JSONPath cannot navigate to parent nodes. There is no equivalent to XPath's .. (parent axis). JSONPath's .. means recursive descent, not parent.

The IETF Standard: RFC 9535

In 2024, the IETF published RFC 9535, which formally standardizes JSONPath. This specification resolves many of the ambiguities and inconsistencies that existed across implementations. Key aspects of the standard include:

• Defined semantics: Precise rules for how each operator behaves, including edge cases like missing keys, null values, and type mismatches in comparisons.
• Normalized syntax: A canonical form for JSONPath expressions that all conforming implementations must support.
• Filter expression specification: Clear rules for filter syntax, including which comparison and logical operators are supported.
• Function extensions: A mechanism for extending JSONPath with custom functions like length(), count(), and match().

If you are starting a new project, prefer libraries that implement RFC 9535 for maximum compatibility and predictable behavior.