JSONPath Syntax: Query JSON Like XPath

Learn JSONPath syntax to query, filter, and extract data from nested JSON structures.

What is JSONPath?

JSONPath is a query language for JSON, analogous to XPath for XML. It lets you navigate and extract data from JSON structures using a concise syntax.

JSONPath is widely used in tools like AWS Step Functions, Kubernetes configurations, API testing tools, and data transformation pipelines.

Basic Syntax

$ — Root element
.key or ['key'] — Access a child key
[n] — Access array element at index n
[*] — Wildcard: all elements of array or object
.. — Recursive descent: search all descendants
[start:end] — Array slice
[?(@.condition)] — Filter expression

Examples

Given: {"store":{"books":[{"title":"Deep Work","price":15},{"title":"Atomic Habits","price":18}]}}

$.store.books[0].title → "Deep Work"
$.store.books[*].title → ["Deep Work", "Atomic Habits"]
$.store.books[?(@.price > 16)].title → ["Atomic Habits"]
$..price → [15, 18] (recursive)

Filter Expressions

Filter expressions use [?(@.field operator value)] syntax. The @ refers to the current element being evaluated.

[?(@.active == true)] — Where active is true
[?(@.price >= 10)] — Where price >= 10
[?(@.name =~ /pattern/)] — Where name matches a regex (implementation-specific)

Frequently Asked Questions

What is the difference between JSONPath and jq?

JSONPath is a query language specification used inside APIs, testing tools, and config systems like AWS Step Functions. jq is a standalone command-line tool with its own syntax for filtering and transforming JSON. JSONPath uses dot notation like $.store.books[0].title, while jq uses pipe-based filtering like .store.books[0].title. JSONPath is better when you need to embed a query in a configuration file or HTTP request; jq is better for ad-hoc terminal work and shell scripting.

Does JSONPath work the same in every language?

No. JSONPath has no single RFC-level standard (though IETF RFC 9535 was published in 2024), so implementations differ. For example, filter expressions like [?(@.price > 10)] are widely supported, but regex matching with =~ is available in some implementations (Jayway JsonPath for Java) and absent in others (Python jsonpath-ng). Always test your JSONPath expressions against the specific library your project uses.

Can JSONPath modify JSON data or only read it?

Standard JSONPath is read-only — it extracts data from a JSON document but does not modify it. If you need to update JSON in place, use a library like jsonpatch (RFC 6902), jq with assignment operators, or language-specific tools like Python's jsonpath-ng-ext which adds set operations on top of JSONPath queries.