JSONPath - RFC9535 compliant JSON Path library

News Announcing
,
1

Hi everyone

I needed a way to evaluate arbitrary JSON Path expressions, and I could not find any existing library that was fully complaint with RFC-9535. The two most popular libraries I found (ExJsonPath and Warpath) predate the RFC and, while sufficient for most common cases, they still contained some incompatible behavior, so I decided to implement a new one from scratch.

Introducing JSONPath, an RFC-9535 compliant JSON Path query evaluator.

Features

  • Passes 100% of the JSONPath Compliance Test Suite.
  • Supports all function extensions: length, count, match, search, value.
  • No external dependencies.
  • Does not support additional function extensions, for example sum, common in pre RFC9535 implementations.
  • Does not support atom keys.

The only discrepancy with RFC9535 is regarding regular expressions. For match and search, the standard expects I-RegExp style expressions, while in JSONPath library any valid Elixir regular expression are accepted.

If you need any of the non-standarised functions/behaviors I would recommend to use any of the pre-RFC libraries. If you need to follow the standard as strictly as possible then consider giving JSONPath a try :grinning_face:

Basic usage

document = [
      %{"name" => "Alice", "age" => 20},
      %{"name" => "Bob", "age" => 30},
      %{"name" => "Charlie", "age" => 25}
    ]
query = "$[?@.age < 27].name"
JSONPath.evaluate(document, query)
# {:ok, ["Alice", "Charlie"]}

Links

11 Likes
2

Congratulations on the release. Do you plan on implementing the ability to validate JSON Path expressions at compile time?

Edit:
I ask because there are PostgreSQL functions which work with JSON Path and it’d be cool to write Ecto helpers which can, at compile time, tell you “hey, this path is wrong”.

1 Like
3

Thank you

The code already checks that the argument is a valid JSON Path expression before doing any evaluation, and returns an error when the expression is invalid. I forgot to include examples both in the README and in the announcement post :sweat_smile: You can find some examples in the project’s README now for invalid expressions. I also added bang functions in case you want to do @query JSONPath.build!(“…”) .

As for SQL integration, unfortunately the syntax is different for SQL/JSON compared to RFC-9535. For example the query "$[?@.age < 27].name” from the example becomes something like "$[*] ? (@.age < 27).name”. My use case is RFC-9535 expressions exclusively, I have no plans at the moment of doing anything with SQL/JSON queries + Ecto.

4

New version 0.3 released

JSONPath.evaluate/3 now takes an optional 3rd argument to specify the returned type. Possible values are:

  • :values - Returns the node values, same as previous versions
  • :paths - Returns the normalized paths
  • :values_and_paths - Returns a list of 2-element tuples {node_value, normalized_path}

Examples:

root = %{"people" => [%{"name" => "Alice", "age" => 20}, %{"name" => "Bob", "age" => 30}]}
query = "$.people[?@.age > 25]"
JSONPath.evaluate(root, query, :values)
# {:ok, [%{"name" => "Bob", "age" => 30}]}

JSONPath.evaluate(root, query, :paths)
# {:ok, ["$['people'][1]"]}

JSONPath.evaluate(root, query, :values_and_paths)
#{:ok, [{%{"name" => "Bob", "age" => 30}, "$['people'][1]"}]}
1 Like
5

That’s a great feature but I have a question. Do you think encoding the different result formats in a single struct makes sense? Changing the return type through a flag argument is a smell in my opinion.

2 Likes
6

Yes I wasn’t fully convinced either. I might change it to 3 separate functions instead in a future version. I also take suggestions if you have a better idea, before I make another questionable decision :grin:

1 Like