JSONPath-NG

1.8.0 · active · verified Sat Mar 28

jsonpath-ng is a robust and significantly extended implementation of JSONPath for Python. It aims to be standard compliant, including arithmetic and binary comparison operators, and provides a clear Abstract Syntax Tree (AST) for metaprogramming. As of version 1.8.0, it is actively maintained with a regular release cadence, merging functionalities from older libraries like jsonpath-rw and jsonpath-rw-ext.

Warnings

breaking Python 3.7 support was removed in v1.7.0. Python 3.8 and 3.9 support were removed in v1.8.0. Users on these Python versions must upgrade to Python 3.10 or newer to use jsonpath-ng >= 1.8.0.
Fix: Upgrade your Python environment to 3.10 or newer.
gotcha The `find()` method returns a list of `DatumInContext` objects, even if only one or no matches are found. Users commonly forget to check if the list is empty before accessing `[0].value`, leading to an `IndexError`.
Fix: Always check if the `matches` list is not empty (e.g., `if matches: value = matches[0].value`) or use a list comprehension if expecting multiple results.
gotcha In older versions, updating a JSON object using `jsonpath_expr.update()` could fail with `TypeError` if the target value was `None` or a boolean. While fixes have been implemented (e.g., for boolean values in v1.7.0, and null values in earlier patches), ensure you are on a recent version if experiencing such issues.
Fix: Upgrade to the latest version of `jsonpath-ng` to benefit from these fixes, especially if performing `update` operations on data that might contain `None` or boolean values.
gotcha The library internally uses `this` to refer to the 'current object' within a filter expression, rather than the `@` symbol often seen in other JSONPath implementations. While `@` might work in simple cases due to parsing ambiguities, `this` is the explicit and recommended syntax for clarity and correctness.
Fix: Use `this` (e.g., `[?(this.price < 10)]`) instead of `@` when referencing the current object within filter expressions.

Install

pip install jsonpath-ng Install latest version

Imports

parse
```
from jsonpath_ng import parse
```
The core `parse` function for standard JSONPath is directly available from `jsonpath_ng`. Use `jsonpath_ng.ext.parse` only for extended features if explicitly needed.
jsonpath
```
from jsonpath_ng import jsonpath
```
Provides programmatic construction of JSONPath expressions without string parsing, though `parse` is more commonly used for string expressions.

Quickstart

This quickstart demonstrates how to parse JSON data, extract specific elements using JSONPath expressions, filter results, and update values within a JSON structure. It covers the core `parse` and `find` methods, as well as a basic `update` operation.

from jsonpath_ng import jsonpath, parse
import json

data = {
    "store": {
        "book": [
            {"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95},
            {"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99},
            {"category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99},
            {"category": "fiction", "author": "J.R.R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99}
        ],
        "bicycle": {"color": "red", "price": 19.95}
    },
    "expensive": 10
}

# Find all book titles
jsonpath_expr = parse('$.store.book[*].title')
matches = jsonpath_expr.find(data)
book_titles = [match.value for match in matches]
print(f"Book Titles: {book_titles}")

# Find books cheaper than $10
jsonpath_expr = parse('$.store.book[?(@.price < 10)].title')
matches = jsonpath_expr.find(data)
cheap_books = [match.value for match in matches]
print(f"Cheap Books (titles): {cheap_books}")

# Update a value (e.g., change bicycle color)
update_expr = parse('$.store.bicycle.color')
updated_data = update_expr.update(data, 'blue')
print(f"Updated Bicycle Color: {updated_data['store']['bicycle']['color']}")

view raw JSON →