Complete Guide to JSONPath with Practical Examples

JSONPath is a query syntax for selecting values from JSON documents. It is useful when an API response or configuration file is deeply nested and you need a precise path instead of manually expanding objects and arrays.

This guide keeps the core syntax, practical examples and implementation cautions in one place so the site does not split the same JSONPath concepts across several near-duplicate articles.

Start at the root

The dollar sign represents the root JSON value:

$

Given this document:

{
  "store": {
    "book": [
      {"title":"Clean Code","price":35.99,"author":"Robert C. Martin"},
      {"title":"The Pragmatic Programmer","price":42.50,"author":"Andrew Hunt"}
    ],
    "bicycle": {"color":"red","price":299}
  }
}

A direct child can be selected with dot notation:

$.store.book

Object properties and bracket notation

Dot notation is concise for ordinary property names. Bracket notation is useful when a key contains spaces, punctuation or characters that do not fit a simple identifier.

$.store.bicycle.color
$["store"]["bicycle"]["color"]

Both expressions target the same nested value when the implementation supports those forms.

Arrays, indexes and wildcards

Array indexes select a specific item:

$.store.book[0].title

A wildcard selects matching values from every array item:

$.store.book[*].title

Expected result:

["Clean Code", "The Pragmatic Programmer"]

Some implementations also support slices or multiple indexes. When portability matters, test the expression in the same library or runtime that will execute it.

Recursive descent

Recursive descent is useful when you know the property name but not its exact depth:

$..price

For the sample above, that can return the two book prices and the bicycle price. Prefer a direct path when the structure is known because a broad recursive search can return more matches than expected.

Filter expressions

Filters select array items using conditions. A common example is selecting books below a price threshold:

$.store.book[?(@.price < 40)]

Filter syntax and supported operators can vary between JSONPath implementations. Do not assume every library supports every extension in exactly the same way.

Practical development uses

• API testing: select a nested field you want to assert without comparing the entire response.
• Debugging: locate a deeply nested property in a large payload.
• Automation: extract a value before passing it to a later workflow step.
• Documentation: record the exact path to a field in a response example.
• Data extraction: retrieve only the fields needed for a report or transformation.

Common mistakes

• Using a property name that does not match the JSON exactly.
• Using the wrong array index; JSON arrays are zero-based.
• Using a broad recursive search when a direct path is available.
• Assuming an optional filter, slice or function is portable across every JSONPath library.
• Treating JSONPath as an editing language; its main purpose is selecting/querying data.

Test the expression against representative data

A query that works on one small sample can still fail when an API omits a field, changes an array shape or uses property names that require bracket notation. Test against representative responses and verify the syntax supported by your target implementation.

The JSON Path Finder can help you inspect nested data and copy candidate paths. The result should still be verified in the environment where the expression will run.

References

• RFC 9535 — JSONPath: Query Expressions for JSON
• RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format