json-path-features

[simbo1905]

Context

We extracted ~349 JsonPath expression strings from the upstream Jayway JsonPath test suite under .tmp/JsonPath/... and compared them with our current JsonPath test coverage (~48 expressions at the time).

Some Jayway features are legacy (pre-Java-8 era) and should not be copied directly. We still want to track remaining feature gaps so we can decide (with tests) what belongs in this project.

Explicitly Out Of Scope

• Path-embedded aggregate functions such as $.numbers.avg(), $.sum(), $.min(), $.max(), etc.
  • Modern Java code should use JsonPath.query(...) + Streams.
  • We provide stream helpers in json-java21-jsonpath (see JsonPathStreams) to filter by type and convert values.

Research Candidates (Not Yet Ruled Out)

1. Regex filters

   • Jayway examples: $[?(@.name =~ /regex/)], $[?(@.name =~ /REGEX/i)]
   • Questions:
     • Do we want =~ at all? If yes, what is the exact regex syntax and escaping rules?
     • Case-insensitive flag handling (/i) and other flags.

2. Multi-property selection in brackets

   • Examples: $['a', 'b', 'c'], $.store.book[*]['author', 'isbn']
   • Decide semantics: preserve ordering? include missing keys? duplicates?

3. in operator in filters

   • Example: $[?(@.category in ['fiction', 'reference'])]
   • Decide type rules: strings only? numbers? null handling?

4. Special key escaping (quotes, commas, backslashes)

   • Examples: $['key,'], $['key\\,'], $['can\\'t delete']
   • Decide escaping rules to match parser/string literal handling.

5. Keys containing dashes/dots (and dot-notation ambiguity)

   • Examples: $.display-price, $['dot.notation'], $..['display-price']
   • Ensure property printing/reconstruction stays stable.

6. Deep nested filters (property-paths inside filters)

   • Examples: $[?(@.foo.bar)], $[?(@.parent.child.name)]
   • Decide supported depth and behavior when intermediate nodes are missing.

Suggested Next Steps

• For each candidate feature:
  • Pick a minimal set of JsonPath expressions from the Jayway string catalog.
  • Add small, explicit tests in json-java21-jsonpath for parsing and evaluation.
  • Decide whether behavior is Goessner-aligned or a deliberate extension.
• Keep the feature list updated as decisions are made.

Reference

• Goessner JSONPath article: https://goessner.net/articles/JsonPath/