What is JSONPath?
JSONPath is a query language for JSON, similar to how XPath works for XML. It provides a standardized way to navigate and extract data from complex JSON structures without writing custom parsing code.
Originally proposed by Stefan Goessner in 2007, JSONPath has become widely adopted in APIs, testing frameworks, and data processing tools. Understanding JSONPath can significantly speed up your data extraction workflows.
Sample JSON for Examples
We'll use this sample JSON throughout the guide:
{ "store": { "name": "TechBooks", "books": [ { "title": "Clean Code", "author": "Robert C. Martin", "price": 44.99, "category": "programming", "inStock": true }, { "title": "The Pragmatic Programmer", "author": "David Thomas", "price": 49.99, "category": "programming", "inStock": true }, { "title": "Design Patterns", "author": "Gang of Four", "price": 59.99, "category": "programming", "inStock": false }, { "title": "JavaScript: The Good Parts", "author": "Douglas Crockford", "price": 29.99, "category": "javascript", "inStock": true } ], "location": { "city": "San Francisco", "country": "USA" } }
}Basic JSONPath Syntax
The Root ($)
Every JSONPath expression starts with $, which represents the root of the JSON document:
$ → Returns the entire JSON object
$.store → Returns the "store" object
$.store.name → Returns "TechBooks"Dot Notation
Use dot notation to access object properties:
$.store.name → "TechBooks"
$.store.location.city → "San Francisco"
$.store.books → [array of all books]Bracket Notation
Use brackets to access array elements by index (0-based) or properties with special characters:
$.store.books[0] → First book object
$.store.books[0].title → "Clean Code"
$.store.books[-1] → Last book (some implementations)
$.store['name'] → "TechBooks" (alternative to dot)Wildcards and Recursion
Asterisk Wildcard (*)
The asterisk matches all elements at the current level:
$.store.books[*] → All book objects
$.store.books[*].title → All book titles: ["Clean Code", "The Pragmatic Programmer",...]
$.store.* → All direct children of store (name, books, location)Recursive Descent (..)
The double-dot operator searches for elements at any depth in the JSON structure:
$..title → All "title" properties anywhere in the document
$..price → All "price" values: [44.99, 49.99, 59.99, 29.99]
$..city → ["San Francisco"] (finds nested property)Array Slicing
Similar to Python, JSONPath supports array slicing with [start:end:step] syntax:
$.store.books[0:2] → First two books (indices 0 and 1)
$.store.books[1:3] → Books at indices 1 and 2
$.store.books[::2] → Every other book (step of 2)
$.store.books[-2:] → Last two books (some implementations)Filter Expressions
Filter expressions [?()] let you select elements based on conditions. The @ symbol represents the current element being evaluated:
Comparison Operators
$.store.books[?(@.price < 50)] → Books priced under $50 $.store.books[?(@.category == 'programming')] → Books in "programming" category $.store.books[?(@.inStock == true)] → Only books that are in stock $.store.books[?(@.price >= 40 && @.price <= 50)] → Books priced between $40 and $50Available Operators
| Operator | Description | Example |
|---|---|---|
== | Equal to | @.status == 'active' |
!= | Not equal to | @.type!= 'draft' |
<, > | Less/Greater than | @.price > 100 |
<=, >= | Less/Greater or equal | @.quantity <= 10 |
&& | Logical AND | @.a > 1 && @.b < 5 |
|| | Logical OR | @.type == 'a' || @.type == 'b' |
Existence Check
Check if a property exists on an object:
$.store.books[?(@.isbn)] → Books that have an ISBN property (would return empty with our sample data) $.store.books[?(@.author)] → Books that have an author property (all of them)Common JSONPath Patterns
1. Get All Values of a Property
// All titles
$.store.books[*].title // All prices across the entire document
$..price2. Find Items Meeting Criteria
// Expensive items (price > 50)
$..books[?(@.price > 50)] // Items by specific author
$..books[?(@.author == 'Douglas Crockford')]3. Nested Object Access
// Access deeply nested property
$.store.location.city // Find property at any depth
$..city4. Combine Multiple Conditions
// Affordable programming books in stock
$.store.books[?(@.category == 'programming' && @.price < 50 && @.inStock == true)]JSONPath vs jq
Both JSONPath and jq are popular tools for querying JSON, but they have different strengths:
| Feature | JSONPath | jq |
|---|---|---|
| Learning Curve | Simpler, XPath-like | Steeper, more powerful |
| Transformation | Read-only queries | Can modify and reshape |
| Library Support | Many languages | Command-line focused |
| Best For | Simple extraction | Complex transformations |
Using JSONPath in JavaScript
import { JSONPath } from 'jsonpath-plus'; const data = { /* your JSON data */ }; // Basic query
const titles = JSONPath({ path: '$.store.books[*].title', json: data });
console.log(titles);
// ["Clean Code", "The Pragmatic Programmer",...] // With filter
const cheapBooks = JSONPath({ path: '$.store.books[?(@.price < 40)]', json: data
}); // Recursive search
const allPrices = JSONPath({ path: '$..price', json: data
});JSONPath Best Practices
- Start Simple: Build queries incrementally, testing each step
- Use Recursive Descent Carefully:
..can be slow on large documents - Prefer Specific Paths:
$.store.books[*].titleis faster than$..title - Test Edge Cases: Consider empty arrays, missing properties, null values
- Document Complex Queries: Add comments explaining what the query extracts
- Handle Multiple Results: Most queries return arrays, even for single matches
Try CoderFile JSONPath Finder
Test JSONPath queries interactively. Paste your JSON, write queries, and see results instantly with syntax highlighting and error messages.
Conclusion
JSONPath is an essential tool for any developer working with JSON data. Its XPath-like syntax makes it intuitive for querying nested structures, while filter expressions provide the flexibility to extract exactly the data you need.
Start with simple queries using dot notation and wildcards, then gradually explore filter expressions and recursive descent as your needs grow. With practice, JSONPath will become an indispensable part of your data processing toolkit.