What JSONPath is for
JSONPath is a query language for JSON, inspired by XPath for XML. Stefan Gössner sketched it in 2007 as a way to address nodes inside a JSON document with a single string expression. After almost two decades of slightly incompatible implementations, the IETF standardised it as RFC 9535 in February 2024.
You reach for JSONPath when you want to extract a value or set of values from a JSON document without writing a full traversal in code. Think of it as the SELECT clause of a database query, scoped to a single document.
// document
{
"store": {
"books": [
{ "title": "Clean Code", "price": 34.99 },
{ "title": "The Pragmatic Programmer", "price": 49.99 }
]
}
}
// "give me every book title"
$.store.books[*].title
// → ["Clean Code", "The Pragmatic Programmer"]The rest of this guide walks through the syntax, what every implementation agrees on, where they disagree, and when to use something else entirely.
The basics: dots and brackets
Every JSONPath expression starts with $, the root. Then you append segments, separated by dots or bracket notation. Both notations mean the same thing for simple keys:
$.store.books // dot notation
$['store']['books'] // bracket notation — equivalentBracket notation is required when a key contains characters that are not valid in an identifier: spaces, hyphens, dots, anything non-ASCII. $.first-name would be parsed as $.first minus name. $['first-name'] is unambiguous.
Most implementations also accept a leading $.. for recursive descent, which we cover below. For now, the rule is: dots descend by one level, brackets do the same with explicit key strings.
Array indexing and slicing
Brackets with a number index into arrays. Zero-based, like every other language since C.
$.books[0] // first book
$.books[2] // third book
$.books[-1] // last book (negative indices, supported by most impls)
$.books[-2] // second to lastYou can also slice ranges using Python-style notation:
$.books[0:3] // first three books (indices 0, 1, 2)
$.books[2:] // from index 2 to the end
$.books[:3] // first three (start defaults to 0)
$.books[::2] // every other book (step of 2)Slice support is universal in the major implementations (Jayway in Java, jsonpath-plus in JavaScript, the Python jsonpath-ng library, and RFC 9535). Negative steps for reversing are RFC 9535 territory and not implemented everywhere.
Wildcards and deep descent
The wildcard * matches every key or every array element at one level.
$.store.books[*] // every book
$.store.books[*].title // every book's title
$.store.* // every value under store (books, owner, etc.)Deep descent, .., is the killer feature. It searches every level of the document for a matching key.
$..title // every "title" key anywhere in the document
$..price // every "price" key anywhere
$..books[*] // every item in any "books" array, no matter how deeply nestedThis is what makes JSONPath powerful for exploring unknown documents. Got a 5,000-line config and want to know what every "timeout" value is set to? $..timeout dumps them all.
Filter expressions
Filters narrow a selection with a boolean expression inside [?( ... )]. The @ symbol refers to the current item being filtered.
// books that cost more than $40
$.store.books[?(@.price > 40)]
// books with an "inStock" key set to true
$.store.books[?(@.inStock == true)]
// books whose title contains "Code"
$.store.books[?(@.title =~ /Code/)]
// chain conditions with && and ||
$.store.books[?(@.price > 20 && @.inStock == true)]Regex (=~), &&, and || are widely supported in JavaScript and Java implementations but were left out of RFC 9535's core grammar — the standard prefers match() and search() functions for regex. Read the docs of the specific library you are using.
Filters compose with everything else. $..books[?(@.price > 40)].title returns the titles of all books over $40, no matter where the books array sits in the document.
Running queries in the browser
For exploring a document interactively, the JSONPath tester on this site evaluates full RFC 9535 expressions, filters included, as you type, and lists every match with its path. The editor has the same engine in its Query panel. It is the fastest way to confirm a path before pasting it into your code.
For programmatic use in JavaScript, jsonpath-plus is the standard. About 30 kB minified, no dependencies:
import { JSONPath } from 'jsonpath-plus';
const data = { /* ... */ };
const result = JSONPath({ path: '$..books[*].title', json: data });
// → ['Clean Code', 'The Pragmatic Programmer']For RFC 9535 compliance specifically, look at @nimajneb/jsonpath-rfc9535 or the official IETF test suite implementations. Most production code is fine with the broader dialect.
JSONPath vs jq
If you spend any time on the command line, you have probably used jq. The two tools overlap heavily but are not interchangeable.
JSONPath is a query language for extracting nodes. Input goes in, a subset comes out. The expression describes which parts of the document to keep.
jq is a full programming language for JSON. It can extract (same as JSONPath), transform (map over arrays, restructure objects, build new documents), do arithmetic, define functions, and pipe results between filters.
# JSONPath: extract titles
$..books[*].title
# jq: extract titles
.. | objects | select(has("title")) | .title
# jq can also do this:
.store.books | map(select(.price > 40) | { title, discounted: .price * 0.9 })Use JSONPath when you want a portable query expression you can embed in config (Logstash filters, AWS IAM conditions, Kubernetes JSONPath selectors all use it). Use jq when you are scripting and need to transform on the way out.
The RFC 9535 standard
RFC 9535 was published in February 2024 to end fifteen years of "every library does it slightly differently." The headline changes from the Gössner draft:
- Formal grammar (ABNF) — no more ambiguity about what is valid syntax.
- Defined evaluation semantics — given a path and a document, every conforming implementation produces the same result.
- Explicit list of comparison operators in filters:
==,!=,<,<=,>,>=. - Functions:
length(),count(),match(),search(),value(). - Two ways to dereference — by node (preserving location) or by value (just the data).
The standard is opt-in. Most existing libraries still ship the older Gössner dialect by default for backward compatibility, with a flag to switch. If you write paths today that need to survive a library upgrade, stick to the intersection of dialects: dots, brackets, *, .., and basic ?() filters with == and arithmetic.
When not to use JSONPath
JSONPath is great for simple extraction. It is bad for three things.
Heavy transformation. If you are mapping every item to a new shape, JSONPath does not have the syntax for it. Use jq, a SQL JSON function (Postgres jsonb_path_query, MySQL JSON_TABLE), or just write the traversal in code.
Schema validation. JSONPath finds nodes; it does not verify shape. Use JSON Schema with Ajv for that.
Editing. JSONPath is read-only. To mutate a document by path, look at JSON Patch (RFC 6902) or JSON Pointer (RFC 6901) instead.
Inside its wheelhouse — "give me these nodes from this document" — JSONPath is the right tool. Twenty bytes of expression replaces twenty lines of nested optional chaining. Start with the dot notation, add brackets when keys have special characters, reach for filters when you need to narrow by content. The rest is library-specific quirks.