JSONPath Query Syntax

JSONPath is a query language for extracting specific values from JSON documents, analogous to XPath for XML. It provides a concise syntax for navigating complex JSON structures and selecting elements based on their position, name, or value, without writing imperative traversal code.

Basic syntax:

The root of a JSON document is represented by $. Properties are accessed with dot notation or bracket notation:

• $.store.book — access the book property inside store
• $['store']['book'] — equivalent bracket notation
• $.store.book[0] — first element of the book array
• $.store.book[-1] — last element of the array (in some implementations)

Key operators:

• $ — The root object
• . — Child operator (dot notation)
• [] — Child operator (bracket notation) or array index
• * — Wildcard, matches all properties or elements
• .. — Recursive descent, searches all levels
• [start:end:step] — Array slice
• [?(expression)] — Filter expression

Practical examples:

Given a bookstore JSON document:

$.store.book[*].author          — All authors of all books
$.store.book[?(@.price < 10)]   — Books cheaper than $10
$..author                       — All authors anywhere in the document
$.store.book[0,1]               — First two books
$.store.book[-2:]               — Last two books

Filter expressions:

Filters use @ to reference the current element:

• [?(@.price > 20)] — elements where price exceeds 20
• [?(@.category == 'fiction')] — elements matching a category
• [?(@.isbn)] — elements that have an isbn property

Implementation landscape:

JSONPath is not a formal standard (though RFC 9535 was published in 2024), and implementations vary across languages. The most common implementations include jsonpath-plus and jsonpath for JavaScript, jsonpath-ng for Python, and Jayway JsonPath for Java. Syntax support for features like filter expressions, regex matching, and slice notation differs between implementations.

Common mistakes developers make:

The biggest mistake is assuming all JSONPath implementations behave identically. Features like negative array indices, regex filters, and function extensions are not universally supported. Another mistake is using JSONPath for data transformation rather than just selection — JSONPath extracts data but does not modify the source document. Developers also sometimes confuse JSONPath with JSON Pointer (RFC 6901), which uses a simpler /key/index syntax for pinpointing a single value rather than querying multiple matches.

Best practices:

Test your JSONPath expressions against your actual data before using them in production code. Stick to widely supported operators ($, ., [], *, ..) for maximum portability. When performance matters, avoid recursive descent (..) on large documents as it traverses the entire tree. Consider JSON Pointer (RFC 6901) if you only need to reference a single specific path rather than query multiple matches.