jsonpath-rust

The library provides the extensive functionality to find data sets according to filtering queries. Inspired by XPath for XML structures, JsonPath is a query language for JSON. The specification is described in RFC 9535.

Important note

The version 1.0.0 has a breaking change. The library has been rewritten from scratch to provide compliance with the RFC9535.

The changes are:

• The library is now fully compliant with the RFC 9535.
• New structures and apis were introduced to provide the compliance with the RFC 9535.
  • Queryable instead of JsonLike
  • Queried<Queryable> instead of Result<Value, JsonPathParserError>
  • JsonPath#{query_with_path, query_only_path, query} to operate with the Queryable structure
  • JsonPathError instead of JsonPathParserError
  • QueryRef to provide the reference to the value and path
• The functions in, nin, noneOf, anyOf, subsetOf are now implemented as custom filter expressions and renamed to in, nin, none_of, any_of, subset_of respectively.
• The function length was removed (the size can be checked using rust native functions for using it in filter there is length expression).

The compliance with RFC 9535

The library is fully compliant with the standard RFC 9535 To check the compliance with the standard head to rfc9535 subfolder

Examples

Given the json

{
 "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
}

Library Usage

Extensions

The library provides the following extensions:

• in
  Checks if the first argument is in the array provided as the second argument. Example: $.elems[?in(@, $.list)] Returns elements from $.elems that are present in $.list.

• nin
  Checks if the first argument is not in the array provided as the second argument. Example: $.elems[?nin(@, $.list)] Returns elements from $.elems that are not present in $.list.

• none_of
  Checks if none of the elements in the first array are in the second array. Example: $.elems[?none_of(@, $.list)] Returns arrays from $.elems that have no elements in common with $.list.

• any_of
  Checks if any of the elements in the first array are in the second array. Example: $.elems[?any_of(@, $.list)] Returns arrays from $.elems that have at least one element in common with $.list.

• subset_of
  Checks if all elements in the first array are in the second array. Example: $.elems[?subset_of(@, $.list)] Returns arrays from $.elems where all elements are present in $.list.

Queryable

The library provides a trait Queryable that can be implemented for any type. This allows you to use the JsonPath methods on your own types.

Queried with path

fn union() -> Queried<()> {
    let json = json!([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);

    // QueryRes is a tuple of (value, path) for references and just value for owned values
    let vec: Vec<QueryRef<Value>> = json.query_with_path("$[1,5:7]")?;
    assert_eq!(
        vec,
        vec![
            (&json!(1), "$[1]".to_string()).into(),
            (&json!(5), "$[5]".to_string()).into(),
            (&json!(6), "$[6]".to_string()).into(),
        ]
    );

    Ok(())
}

Queried without path

fn exp_no_error() -> Queried<()> {
    let json = json!([
      {
        "a": 100,
        "d": "e"
      },
      {
        "a": 100.1,
        "d": "f"
      },
      {
        "a": "100",
        "d": "g"
      }
    ]);

    let vec: Vec<&Value> = json.query("$[?@.a==1E2]")?;
    assert_eq!(
        vec.iter().collect::<Vec<_>>(),
        vec![&json!({"a":100, "d":"e"})]
    );

    Ok(())
}

Queried with only path

fn filter_data() -> Queried<()> {
    let json = json!({
      "a": 1,
      "b": 2,
      "c": 3
    });

    let vec: Vec<String> = json
        .query_only_path("$[?@<3]")?
        .into_iter()
        .map(Option::unwrap_or_default)
        .collect();

    assert_eq!(vec, vec!["$['a']".to_string(), "$['b']".to_string()]);

    Ok(())
}

Update the Queryable structure by path

The library does not provide the functionality to update the json structure in the query itself. Instead, the library provides the ability to update the json structure by the path. Thus, the user needs to find a path for the JsonLike structure and update it manually.

There are two methods in the Queryable trait:

• reference_mut - returns a mutable reference to the element by the path
• reference - returns a reference to the element by the path

They accept a JsonPath instance and return a Option<&mut Self> or Option<&Self> respectively.

The path is supported with the limited elements namely only the elements with the direct access:

• root
• field
• index

 fn update_by_path_test() -> Queried<()> {
    let mut json = json!([
            {"verb": "RUN","distance":[1]},
            {"verb": "TEST"},
            {"verb": "DO NOT RUN"}
        ]);

    let path = json.query_only_path("$.[?(@.verb == 'RUN')]")?;
    let elem = path.first().unwrap_or_default();

    if let Some(v) = json
        .reference_mut(elem)
        .and_then(|v| v.as_object_mut())
        .and_then(|v| v.get_mut("distance"))
        .and_then(|v| v.as_array_mut())
    {
        v.push(json!(2))
    }

    assert_eq!(
        json,
        json!([
                {"verb": "RUN","distance":[1,2]},
                {"verb": "TEST"},
                {"verb": "DO NOT RUN"}
            ])
    );

    Ok(())
}

Python bindings

Python bindings (jsonpath-rust-bindings) are available on pypi:

pip install jsonpath-rust-bindings

How to contribute

TBD

How to update version

• update files
• commit them
• add tag git tag -a v<Version> -m "message"
• git push origin <tag_name>