JSONPath Query Syntax Guide: Expressions, Filters, and Practical Examples

Introduction: Why JSONPath Matters for Modern Development

JSON has become the dominant data interchange format across web APIs, configuration files, databases, and message queues. As JSON documents grow in complexity — deeply nested objects, arrays with hundreds of elements, mixed-type structures — manually navigating them becomes impractical. JSONPath provides a concise, standardized expression language for selecting and extracting specific values from JSON documents, much like XPath does for XML.

Originally proposed by Stefan Goessner in 2007, JSONPath has since been formalized as RFC 9535 (published February 2024), giving the language an official specification after years of informal, implementation-driven evolution. Whether you are debugging API responses, writing automated tests, transforming data pipelines, or building configuration management tools, understanding JSONPath syntax is a practical skill that saves hours of manual inspection.

This guide covers every JSONPath operator with clear examples, compares JSONPath to XPath and jq, and demonstrates common extraction patterns against realistic API responses. Use our JSONPath Query tool to practice these expressions interactively — all processing happens locally in your browser.

JSONPath Syntax: The Complete Reference

A JSONPath expression is a string that describes a path through a JSON document. Every expression starts with $, which represents the root of the document. From there, you chain operators to drill into objects, iterate arrays, and filter results. Below is each operator explained with examples against a sample document.

Consider this sample JSON document used throughout the examples:

{
"store": {
"name": "TechBooks Online",
"books": [
{ "title": "Design Patterns", "author": "GoF", "price": 49.99, "tags": ["software", "oop"] },
{ "title": "Refactoring", "author": "Fowler", "price": 44.95, "tags": ["software", "agile"] },
{ "title": "The Pragmatic Programmer", "author": "Hunt", "price": 39.99, "tags": ["software", "career"] },
{ "title": "Clean Code", "author": "Martin", "price": 34.99, "tags": ["software", "craftsmanship"] },
{ "title": "Mythical Man-Month", "author": "Brooks", "price": 29.99, "tags": ["management", "classic"] }
],
"location": { "city": "Portland", "state": "OR" }
}
}

Root Operator: $

The dollar sign $ always refers to the root element of the JSON document. Every JSONPath expression must begin with $. By itself, $ returns the entire document. It is the anchor from which all path traversals begin.

Expression: $ — Returns the entire JSON object.

Child Operator: Dot Notation . and Bracket Notation ['...']

The dot operator . accesses a named child property of an object. It is the most frequently used operator and mirrors JavaScript's property access syntax. For property names that contain special characters, spaces, or start with a digit, use bracket notation ['property-name'] instead.

• $.store.name — Returns "TechBooks Online"
• $.store.location.city — Returns "Portland"
• $.store['name'] — Equivalent to $.store.name

Bracket notation is required when keys contain dots, hyphens, or spaces (e.g., $['content-type']). Both forms produce the same result for simple alphanumeric keys.

Recursive Descent: ..

The double-dot operator .. searches the entire subtree beneath the current node. It is extremely useful when you know a property name exists somewhere deep in the document but you do not know (or do not care about) the exact path.

• $..author — Returns all author values at any depth: ["GoF", "Fowler", "Hunt", "Martin", "Brooks"]
• $..price — Returns all price values: [49.99, 44.95, 39.99, 34.99, 29.99]
• $..tags — Returns all tags arrays

Recursive descent is powerful but can be expensive on very large documents because it visits every node in the subtree. Use it when the structure is unpredictable or when you need to aggregate values scattered across different levels of nesting.

Wildcard: *

The wildcard * matches all children of the current node, whether they are object properties or array elements. It is useful for iterating all elements at a given level without knowing their names or indices.

• $.store.books[*].title — Returns all book titles: ["Design Patterns", "Refactoring", "The Pragmatic Programmer", "Clean Code", "Mythical Man-Month"]
• $.store.* — Returns the values of all direct children of store: the name string, the books array, and the location object

Array Index: [n]

Square brackets with a zero-based integer index select a specific element from an array. Negative indices count from the end of the array, with [-1] being the last element.

• $.store.books[0] — Returns the first book object (Design Patterns)
• $.store.books[-1] — Returns the last book object (Mythical Man-Month)
• $.store.books[0].title — Returns "Design Patterns"

Array Slice: [start:end:step]

The slice operator selects a range of array elements, following the same semantics as Python's slice notation. The syntax is [start:end:step], where start is inclusive, end is exclusive, and step controls the stride. All three components are optional.

• $.store.books[0:2] — Returns the first two books (index 0 and 1)
• $.store.books[1:4] — Returns books at index 1, 2, and 3
• $.store.books[-2:] — Returns the last two books
• $.store.books[::2] — Returns every other book (index 0, 2, 4)

Slicing is particularly useful for pagination-like operations — extracting a window of results from a large array without needing to know the total count.

Union: [n,m]

The union operator selects multiple specific indices or property names in a single expression, returning results from all specified locations.

• $.store.books[0,2,4] — Returns the first, third, and fifth books
• $.store.books[0,2].title — Returns ["Design Patterns", "The Pragmatic Programmer"]

Filter Expressions: [?()]

Filter expressions are the most powerful JSONPath feature. They allow you to select elements that match a boolean condition. The filter is enclosed in [?()], and @ refers to the current element being evaluated.

• $.store.books[?(@.price < 40)] — Returns books with price less than 40
• $.store.books[?(@.author == 'Fowler')] — Returns books by Fowler
• $.store.books[?(@.price >= 40 && @.price <= 50)] — Returns books priced between 40 and 50
• $.store.books[?(@.tags[0] == 'software')] — Returns books whose first tag is "software"

Filters support the comparison operators ==, !=, <, >, <=, >= and the logical operators && (and), || (or). Some implementations also support string matching functions and regular expressions within filters.

JSONPath vs XPath: Mapping Concepts

JSONPath was originally designed as a JSON analog to XPath, the query language for XML. If you already know XPath, the following mapping helps you translate your existing knowledge:

• / in XPath becomes . (dot) in JSONPath — both navigate to a child element
• // in XPath becomes .. in JSONPath — recursive descent through all descendants
• * works identically in both languages — wildcard matching all children
• [n] works similarly, but XPath arrays are 1-based while JSONPath arrays are 0-based
• XPath predicates [condition] map to JSONPath filters [?(condition)]
• XPath has axes (parent, ancestor, following-sibling) that JSONPath does not support — JSONPath only traverses downward

The key conceptual difference is that XPath operates on a tree of nodes with attributes, text content, and namespaces, while JSONPath operates on a simpler structure of objects, arrays, and primitive values. JSONPath expressions are typically shorter and more intuitive for JSON data because JSON's structure is inherently simpler than XML's.

Another important distinction: XPath can navigate upward to parent and ancestor nodes, while standard JSONPath can only traverse downward from the root. This means that in JSONPath, you cannot select a parent object based on a child's value — you can only filter arrays of objects based on their own properties.

JSONPath vs jq: Different Tools for Different Contexts

While JSONPath is a query language embedded within applications and APIs, jq is a standalone command-line tool and language for transforming JSON. They serve overlapping but distinct purposes:

• Querying (selection): Both JSONPath and jq can extract values from JSON. JSONPath uses $.store.books[0].title, while jq uses .store.books[0].title — the syntax is nearly identical for simple paths.
• Transformation: jq can create new JSON structures, perform arithmetic, concatenate strings, group and sort data, and pipe results through multiple stages. JSONPath is purely a selection language — it extracts existing values but does not transform them.
• Filtering: JSONPath's [?(@.price < 40)] maps to jq's select(.price < 40). Both are expressive for basic conditions. jq is more powerful for complex multi-condition logic with variables and functions.
• Environment: JSONPath is available as a library in virtually every programming language (JavaScript, Python, Java, Go, PHP, C#) and can be embedded in APIs, databases (PostgreSQL, MySQL), and configuration files. jq is primarily a command-line tool, though libraries exist for programmatic use.
• Learning curve: JSONPath's syntax is simpler and can be learned in minutes. jq is a complete functional programming language with pipes, variables, conditionals, and user-defined functions — more powerful but with a steeper learning curve.

In practice, use JSONPath when you need to embed queries inside application code, API parameters, or configuration files (e.g., Kubernetes JSONPath templates, AWS Step Functions). Use jq when processing JSON on the command line or in shell scripts where its transformation capabilities shine.

Practical Examples: Querying Real API Responses

The true value of JSONPath becomes apparent when working with real-world API responses. Here are common patterns you will encounter regularly.

REST API Paginated Response

A typical paginated API response wraps data in a metadata envelope:

{
"data": [
{ "id": 1, "name": "Alice", "role": "admin", "active": true },
{ "id": 2, "name": "Bob", "role": "editor", "active": true },
{ "id": 3, "name": "Charlie", "role": "viewer", "active": false }
],
"meta": { "total": 150, "page": 1, "perPage": 3 }
}

• $.data[*].name — Extract all user names: ["Alice", "Bob", "Charlie"]
• $.data[?(@.active == true)].name — Only active users: ["Alice", "Bob"]
• $.data[?(@.role == 'admin')] — Find admin users
• $.meta.total — Get total record count: 150

Nested Configuration Object

Application configurations frequently nest settings several levels deep:

{
"app": {
"database": {
"primary": { "host": "db1.example.com", "port": 5432 },
"replica": { "host": "db2.example.com", "port": 5432 }
},
"cache": { "host": "redis.example.com", "port": 6379 }
}
}

• $..host — Find all host values at any depth: ["db1.example.com", "db2.example.com", "redis.example.com"]
• $..port — Find all port values: [5432, 5432, 6379]
• $.app.database.primary.host — Get specific primary database host

GraphQL-Style Nested Response

GraphQL responses often include deeply nested relationships:

{
"data": {
"repository": {
"issues": {
"nodes": [
{ "title": "Bug in login", "state": "OPEN", "labels": { "nodes": [{ "name": "bug" }, { "name": "urgent" }] } },
{ "title": "Add dark mode", "state": "OPEN", "labels": { "nodes": [{ "name": "feature" }] } },
{ "title": "Fix typo", "state": "CLOSED", "labels": { "nodes": [{ "name": "docs" }] } }
]
}
}
}
}

• $.data.repository.issues.nodes[*].title — All issue titles
• $.data.repository.issues.nodes[?(@.state == 'OPEN')].title — Open issues only
• $..labels.nodes[*].name — All label names across all issues

Common JSONPath Patterns and Recipes

Certain extraction patterns come up repeatedly across different use cases. Here is a quick reference of recipes you can adapt to your specific data structures.

Extract a Flat List from Nested Arrays

When data is nested inside arrays of arrays, the recursive descent and wildcard operators combine to flatten the results. For example, $..items[*].name extracts all name values from any items array at any level of nesting, regardless of how many layers deep the array is embedded.

Check for Existence of a Property

Some JSONPath implementations support an existence check within filters. The expression $.data[?(@.email)] selects only objects that have an email property defined (not null, not absent). This is useful when dealing with inconsistent API responses where optional fields may or may not be present.

Combine Multiple Conditions

Complex filters use logical operators to combine conditions: $.products[?(@.price > 10 && @.price < 100 && @.inStock == true)] selects products within a price range that are also in stock. Use parentheses to group conditions when mixing && and || to ensure correct evaluation order.

Select the Last N Elements

Negative slicing makes it easy to grab the tail of an array. $.logs[-5:] returns the last five log entries from an array, which is a common pattern when displaying recent activity or the latest error messages from a log stream.

JSONPath in the Ecosystem: Where It Is Used

JSONPath is not just a theoretical query language — it is embedded in many production tools and platforms:

• Kubernetes: The kubectl get command supports -o jsonpath='{...}' output formatting, allowing you to extract specific fields from resource descriptions directly in your terminal.
• PostgreSQL: The jsonb_path_query function supports SQL/JSON Path, which is based on the same concepts as JSONPath and uses similar syntax for querying JSONB columns.
• AWS Step Functions: Input and output processing in state machine definitions uses JSONPath expressions (prefixed with $.) to route data between steps.
• Jayway JsonPath (Java): The most widely used Java implementation, commonly used in Spring Boot applications and REST Assured API testing.
• API testing tools: Postman, REST Assured, Karate, and similar tools use JSONPath to write assertions against API response bodies.
• Azure Logic Apps and Power Automate: JSONPath expressions are used in condition evaluations and data mapping within workflow automation.

Best Practices for Writing JSONPath Expressions

Following these guidelines will make your JSONPath expressions more robust, maintainable, and portable across implementations:

• Be as specific as possible. Prefer $.store.books[*].title over $..title when you know the exact path. Specific paths are faster and less likely to return unexpected results from unrelated parts of the document.
• Use recursive descent sparingly. The .. operator searches every node in the subtree. On large documents (megabytes of JSON), this can be slow. Use it when the structure is genuinely unpredictable.
• Test against edge cases. An empty array, a missing property, a null value, and a document with a single element all exercise different code paths. Verify that your expression handles each correctly.
• Document your expressions. JSONPath expressions embedded in configuration files or test assertions should have a comment explaining what they extract and why, especially for complex filter expressions.
• Be aware of implementation differences. Despite RFC 9535, not all libraries implement every feature identically. Test your expressions in the specific library you are using. Our JSONPath Query tool uses a standards-compliant implementation that you can use as a reference baseline.
• Prefer bracket notation for special characters. If a key contains dots, spaces, or hyphens, always use $['my-key'] rather than attempting dot notation, which will fail or produce unexpected results.

Conclusion: JSONPath as a Core Developer Skill

JSONPath bridges the gap between raw JSON data and the specific values your application needs. Its concise syntax — root $, child ., recursive .., wildcard *, index [n], slice [start:end], and filter [?()] — covers the vast majority of data extraction scenarios you will encounter in practice. With RFC 9535 providing a formal specification, JSONPath is no longer a loose collection of compatible-but-different implementations; it is a standardized tool you can rely on across languages and platforms.

For quick experimentation and validation of your JSONPath expressions, use our JSONPath Query tool. Paste your JSON, write your expression, and see results instantly — with all processing happening entirely in your browser for complete privacy.