DEV Community

Deepak Kumar
Deepak Kumar

Posted on Originally published at jsonformatterhub.com

JSONPath — How to Query and Filter JSON Data

#json #jsonpath #webdev #api

JSONPath is a query language for JSON, providing the same kind of document-navigation power that XPath gives XML developers. Instead of writing nested loops or chained property accesses, you write a compact expression that pinpoints exactly the data you need — whether it lives three levels deep or is scattered across a hundred-element array.

What Is JSONPath and Why Does It Matter?

Stefan Goessner introduced JSONPath in 2007 as a direct analog to XPath 1.0 for XML. Just as XPath lets you write //book[@price<10] to pluck cheap books out of an XML document tree, JSONPath lets you write $.store.book[?(@.price < 10)] to do the same against a JSON structure.

The practical value is highest when working with API responses you don't fully control. Rather than parsing the entire payload and walking the object graph yourself, you hand a JSONPath expression to a library and get back exactly the nodes you care about. This approach is used by REST-testing frameworks like REST Assured in Java, by AWS's query language JMESPath in the AWS CLI, and by the widely used jq command-line tool (which has its own syntax but borrows heavily from the same ideas).

The Root Operator and Basic Navigation

Every JSONPath expression starts with $, representing the root of the document. From there you navigate using dot notation or bracket notation.

$.store.book.title
Enter fullscreen mode Exit fullscreen mode

This reads as: "start at root, enter store, then book, then title." Bracket notation is required when a key contains a hyphen, space, or starts with a digit:

$['store']['book']['title']
$['content-type']
Enter fullscreen mode Exit fullscreen mode

Sample document used throughout this article:

{
  "store": {
    "book": [
      { "title": "Sayings of the Century", "author": "Nigel Rees",     "price": 8.95  },
      { "title": "Sword of Honour",        "author": "Evelyn Waugh",   "price": 12.99 },
      { "title": "Moby Dick",              "author": "Herman Melville","price": 8.99  },
      { "title": "The Lord of the Rings",  "author": "J.R.R. Tolkien", "price": 22.99 }
    ],
    "bicycle": { "color": "red", "price": 19.95 }
  }
}
Enter fullscreen mode Exit fullscreen mode

$.store.bicycle.color returns "red". $.store.book[0].title returns "Sayings of the Century".

Wildcards and Recursive Descent

The wildcard * matches all properties or elements at the current level:

$.store.book[*].author
// ["Nigel Rees", "Evelyn Waugh", "Herman Melville", "J.R.R. Tolkien"]
Enter fullscreen mode Exit fullscreen mode

The recursive descent operator .. searches at any depth, not just the current level:

$..author
Enter fullscreen mode Exit fullscreen mode

This finds every author field anywhere in the document tree, regardless of nesting depth — invaluable when you don't know the exact structure of a deeply nested API response but do know the key name. It can also be combined with a wildcard or index, e.g. $..[0] returns the first element of every array found anywhere in the document.

Array Slicing and Index Access

JSONPath supports Python-style array slicing:

$.store.book[0]      /* first book */
$.store.book[-1]     /* last book (negative index) */
$.store.book[0,2]    /* first and third books (union) */
$.store.book[0:2]    /* first two books (slice, exclusive end) */
$.store.book[1:3]    /* second and third books */
$.store.book[*]      /* all books */
Enter fullscreen mode Exit fullscreen mode

The slice [start:end] follows Python convention — start is inclusive, end is exclusive. Negative indices count from the end, so [-1] always gives the last element regardless of array length — cleaner than computing array.length - 1 in application code.

Filter Expressions

Filter expressions select array elements matching a condition, using [?( expression )] where @ refers to the current element:

/* books costing less than $10 */
$.store.book[?(@.price < 10)]

/* books that have an isbn property */
$.store.book[?(@.isbn)]

/* books priced between $8 and $13 */
$.store.book[?(@.price >= 8 && @.price <= 13)]
Enter fullscreen mode Exit fullscreen mode

Filters are evaluated per element — @ is bound to each array element in turn, and only elements where the expression is true are included. The first example above returns the two books priced at $8.95 and $8.99.

A more real-world example — extracting users whose email domain is gmail.com:

$.users[?(@.email =~ /.*@gmail\.com$/)]
Enter fullscreen mode Exit fullscreen mode

Note that regex support (=~) is available in some implementations (notably the Jayway Java library) but isn't part of the original Goessner spec — check your library's docs for which operators are supported.

Built-in Functions

RFC 9535 (the JSONPath 2.0 spec, published 2024) formalizes a set of built-in functions:

$.store.book.length()          /* number of books */
$.store.keys()                 /* all keys of the store object */
$.store.book[*].price.min()    /* minimum price across all books */
$.store.book[*].price.max()    /* maximum price */
$.users[?( match(@.name, "A.*") )]   /* string matching */
Enter fullscreen mode Exit fullscreen mode

length() is especially useful inside filters: $.users[?( length(@.tags) > 2 )] returns only users with more than two tags. RFC 9535's match() and search() functions use I-Regexp patterns — match() requires a full-string match, search() succeeds if the pattern matches anywhere in the string.

Practical Examples

Extract all email addresses from a user list:

{
  "users": [
    { "id": 1, "name": "Alice", "email": "alice@example.com" },
    { "id": 2, "name": "Bob",   "email": "bob@example.com"   },
    { "id": 3, "name": "Carol", "email": "carol@example.com" }
  ]
}
Enter fullscreen mode Exit fullscreen mode 
$.users[*].email
// ["alice@example.com", "bob@example.com", "carol@example.com"]
Enter fullscreen mode Exit fullscreen mode

Find all books under $15:

$.store.book[?(@.price < 15)]
// Returns the three objects priced 8.95, 12.99, and 8.99
Enter fullscreen mode Exit fullscreen mode

Get the last element when array length is unknown:

$.store.book[-1]
// Returns the Lord of the Rings object
Enter fullscreen mode Exit fullscreen mode

Where JSONPath Is Used in Practice

REST Assured (Java) ships with built-in JSONPath support for API test assertions:

given().when().get("/books").then().body("store.book[0].title", equalTo("Sayings of the Century"));
Enter fullscreen mode Exit fullscreen mode

JMESPath is AWS's answer to JSONPath, used by the AWS CLI's --query flag. The syntax differs (no $ root), but the concept is identical:

aws ec2 describe-instances --query "Reservations[*].Instances[?State.Name=='running'].InstanceId"
Enter fullscreen mode Exit fullscreen mode

jq is the de facto standard for JSON processing on the command line. It has its own richer syntax, but many core ideas — .foo for property access, .[] for iteration, select() for filtering — map directly onto JSONPath concepts. Once you know JSONPath, picking up jq is straightforward.

JSONPath vs. JavaScript Dot-Notation Chaining

In JavaScript, plain property access (data.store.book[0].title) works fine for deterministic paths, but has real limits: if any intermediate property is undefined, the expression throws a TypeError. You need optional chaining (data?.store?.book?.[0]?.title) to be safe, and there's no built-in way to express "all elements" or "any depth."

JSONPath handles both cases with a single expression, and returns an array of matches (zero, one, or many) — which maps naturally onto scenarios expecting multiple results. For simple, known-path access, plain JS dot notation is fine. For flexible querying, filtering, and deep searches across variable-shaped data, a proper JSONPath library is the better tool.

Summary

The core operators to know: $ (root), . and [] (navigation), * (wildcard), .. (recursive descent), array slices ([0] / [-1] / [0:3]), and filter expressions ([?(@.price < 10)]). These seven cover the vast majority of real-world data-extraction tasks — for testing APIs, querying cloud resources, or processing large JSON payloads on the command line.

Want to test JSONPath expressions on your own data? JSON Formatter Hub lets you paste JSON and explore the structure interactively, entirely in your browser.

Top comments (0)