Version 2.0.1

Fixes

• Fixed JSON pointers with negative indices.

  Previously, negative indices were resolved against array-like values, but the JSON Pointer specification (RFC 6901) does not permit negative array indexes. We now raise a JSONPointerIndexError when a JSON Pointer attempts to resolve an array element using a negative index.

  For users who require negative indices in JSON Pointers, you can set JSONPointer.min_int_index to a suitably negative integer, like JSONPointer.min_int_index = -(2**53) + 1.

  See #116.

• Fixed the JSON Patch add operation.

  Previously, a JSONPatchError was raised when pointing to an array index equal to the array's length. Now we append to arrays in such cases. See #117.

Version 2.0.0

JSONPath syntax changes

These breaking changes affect the default configuration of Python JSONPath. Version 2 also introduces a new strict mode, which enforces full compliance with RFC 9535. See optional dependencies and the syntax guide for details.

• Bracket notation - unquoted property names are no longer treated as quoted names.
  • Before: $[foo], $['foo'], and $["foo"] were equivalent.
  • Now: $[foo] is a singular query selector. With an implicit root identifier, $.a[b] is equivalent to $.a[$.b]. See Singular query selector.
• Filter expressions - float literals must follow the RFC.
  • .1 is now invalid (use 0.1)
  • 1. is now invalid (use 1.0)
• Slice selectors - indexes and steps must follow the RFC.
  • Leading zeros and negative zero are no longer valid and raise JSONPathSyntaxError.
• Dot notation - no whitespace is allowed between . or .. and the following name. Whitespace before the dot is still permitted.

JSONPath function extension changes

• Added the startswith(value, prefix) function extension. Returns True if both arguments are strings and prefix is a prefix of value. See the filter functions documentation.
• Reimplemented the non-standard keys() function extension. It used to be a simple Python function, jsonpath.function_extensions.keys. Now it is a "well-typed" class, jsonpath.function_extensions.Keys. See the filter functions documentation.
• Added cache_capacity, debug and thread_safe arguments to jsonpath.function_extensions.Match and jsonpath.function_extensions.Search constructors.

JSONPath features

• Added the Keys filter selector.
• Added the Singular query selector.
• Match and search function extensions now use the regex package (if installed) instead of re. See optional dependencies.
• Added the strict argument to all convenience functions, the CLI and the JSONPathEnvironment constructor. When strict=True, all non-standard extensions and relaxed parsing rules are disabled.
• Added class variable JSONPathEnvironment.max_recursion_depth to control the maximum recursion depth of descendant segments.
• Improved exception messages (prettier, more informative).

Python API changes

• Renamed class variable JSONPathEnvironment.fake_root_token to JSONPathEnvironment.pseudo_root_token.

Low level API changes

These only affect projects customizing the JSONPath lexer or parser.

• The tokens produced by the JSONPath lexer have changed. Previously we broadly skipped some punctuation and whitespace. Now the parser can make better choices about when to accept whitespace and do a better job of enforcing dots.
• We've change the internal representation of compiled JSONPath queries. We now model segments and selectors explicitly and use terminology that matches RFC 9535.

Version 1.3.2

Fixes

• Fixed JSONPath filter context data in embedded JSONPath queries. We were failing to pass on said context data when resolving embedded queries. See #103.

Version 1.3.1

Fixes

• Fixed the non-standard JSON Patch operation, addap. Previously it was behaving like addne. See #81.
• Fixed JSON Patch ops that operate on mappings and have a target that looks like an int. We now ensure the target is a string. See #82.

Version 1.3.0

Fixes

• Fixed jsonpath.JSONPathMatch.path. It is now a "normalized path" following section 2.7 of RFC 9535.
• Fixed normalized slice indexes. We were failing to normalize some indexes given a negative step.

Other changes

• jsonpath.match.NodeList is now re-exported as jsonpath.NodeList.
• Added jsonpath.NodeList.paths(), which returns a list of normalized paths, one for each node in the list.
• Serialization of compiled JSONPath queries (instances of jsonpath.JSONPath) has changed. String literals inside filter selectors are now serialized using the canonical format, as described in section 2.7 of RFC 9535, and parentheses in filter selectors are kept to a minimum.

Version 1.2.2

Fixes

• Fixed parsing of bare name selectors that start with a reserved word. See issue #72.

Changes

• We've dropped support for Python 3.7, which was end of life in June 2023.

Version 1.2.1

Fixes

• Fixed the string representation regex literals in filter expressions. See issue #70.

Version 1.2.0

Fixes

• Fixed handling of JSONPath literals in filter expressions. We now raise a JSONPathSyntaxError if a filter expression literal is not part of a comparison, membership or function expression. See jsonpath-compliance-test-suite#81.
• Fixed parsing of number literals including an exponent. Upper case 'e's are now allowed.
• Fixed handling of trailing commas in bracketed selection lists. We now raise a JSONPathSyntaxError in such cases.

Compliance

• Skipped tests for invalid escape sequences. The JSONPath spec is more strict than Python's JSON decoder when it comes to parsing \u escape sequences in string literals. We are adopting a policy of least surprise. The assertion is that most people will expect the JSONPath parser to behave the same as Python's JSON parser. See jsonpath-compliance-test-suite #87.
• Skipped tests for invalid integer and float literals. Same as above. We are deliberately choosing to match Python's int and float parsing behavior. See jsonpath-compliance-test-suite #89.
• Skipped tests for incorrect casing true, false and null literals.

Features

• Allow JSONPath filter expression membership operators (contains and in) to operate on object/mapping data as well as arrays/sequences. See #55.
• Added a select() method to the JSONPath query iterator interface, generating a projection of each JSONPath match by selecting a subset of its values.
• Added the query() method to the JSONPath class. Get a query iterator from an already compiled path.
• Added the addne and addap operations to JSONPatch. addne (add if not exists) is like the standard add operation, but only adds object keys/values if the key does not exist. addap (add or append) is like the standard add operation, but assumes an index of - if the target index can not be resolved.

Version 1.1.1

Fixes

• Fixed evaluation of JSONPath singular queries when they appear in a logical expression and without a comparison operator. Previously we were evaluating logical expressions with the value held by the single element node list, now we treat such filter queries as existence tests. See #57.

Version 1.1.0

Fixes

• Fixed logical operator precedence in JSONPath filter expressions. Previously, logical or (||) and logical and (&&) had equal precedence. Now && binds more tightly than ||, as per RFC 9535.
• Fixed JSONPath bracketed selector list evaluation order. Previously we were iterating nodes for every list item, now we exhaust all matches for the first item before moving on to the next item.

Features

• Added the "query API", a fluent, chainable interface for manipulating JSONPathMatch iterators (docs, source).