Reading a path from left to right
A JSONPath expression is a series of steps. It starts from $, the whole document, and each step narrows or expands the current set of values. The sample data loaded on this page is a small store:
{"store": {"book": [{"author": "John", "price": 9.99},
{"author": "Jane", "price": 12.99}],
"bicycle": {"color": "red", "price": 19.99}}}
Consider $.store.book[0].price. $ holds the document, .store moves into that object, .book moves to the array, [0] takes its first element and .price reads a field from it. The result is [9.99]. Stefan Goessner sketched this syntax in a 2007 article as an XPath for JSON, and for nearly two decades every library interpreted the details slightly differently, until the IETF published a formal standard, RFC 9535, in February 2024. This evaluator follows that standard.
The selectors, with results
All of these run against the sample above:
$.store.bicycle.color ["red"]
$.store.book[*].price [9.99,12.99]
$.store.book[-1].price [12.99]
$.store.book[0:1].price [9.99]
$.store.book[0,1].price [9.99,12.99]
$..price [9.99,12.99,19.99]
$.store.book[?(@.price>10)].price [12.99]
- [*] takes every element of an array or every value of an object.
- [-1] counts from the end of an array.
- [start:end:step] is a slice, like Python. The end is excluded, so [0:1] is one item, [::2] is every second item and [::-1] reverses the list.
- [0,1] is a union, returning several selections in the order you list them.
- .. is recursive descent. It visits every level, so $..price finds the two book prices and the bicycle price without you naming their parents.
- ['odd key'] is the bracket form for names with spaces or punctuation, which dot notation cannot express.
Recursive descent reaches further than you may expect. On this small document, $..* returns 11 values, since it includes every object and array as well as every number and string inside them.
Writing filters
A filter keeps only the children that pass a test. Inside it, @ means the item being tested and $ still means the document root. The comparison operators are ==, !=, <, <=, > and >=, and tests combine with &&, || and !.
$.store.book[?(@.price > 10)]
$.store.book[?(@.price < 10 || @.author == "Jane")]
$.store.book[?(@.price < $.store.bicycle.price)]
Two behaviours trip people up. First, a bare path is an existence test, not a truth test. [?(@.sold)] matches every item that has a sold field, including items where sold is false. To test the value, write [?(@.sold == true)]. Second, comparing different types is never an error, it is just false, so if a price is stored as the string "10", then @.price > 5 will not match it. When a filter returns nothing and you are sure the data is there, check the quotes around the values.
A filter here runs through a small parser and never executes your expression as code. Some older JSONPath libraries passed filters to JavaScript's eval, which turned a query box into a security hole, so check which approach any library you add to a server takes.
Using it on a real API response
A typical job is pulling a few fields out of a response too large to read. Paste the JSON, run $.* to see the top-level values, then step inwards one level at a time until you reach what you want. Replace an index with [*] once the path works for a single record. Building it up this way is quicker than writing the whole expression and guessing which step failed, because the result updates as you type, and a typo shows a syntax error with its position.
Results are useful in test assertions, webhook mappings and no-code automation tools, many of which take a JSONPath as input. If you are copying an expression to another product, test there as well. Jayway for Java, the jsonpath-ng Python package and Kubernetes' kubectl each have their own extensions and edge cases, and jq is a different language altogether. Many of them return a bare value for a single match where the standard returns a one-item list.