json-pointer

Preamble

This crate is a generalization of the json-pointer crate.

It opens up the target of the JSON pointer to anything that can be adapted using the JsonPointerTarget trait. The odd name of the crate (.simd) comes from the first use case and first attempt at implementation -

• using JSON Pointers with simd-json Values.

But one learns in these efforts and the back-implementation of the JsonPointerTarget trait to re-include [serde_json] values became pretty obvious pretty quickly!

HOPEfully, then, this crate is a stop-gap to getting all this merged back into json-pointer at some point in the future. Before then there is a lot to do -features, tests, docs, better semantics ...

Apart from the JsonPointerTarget-related refactoring, I have also made some updates to the code to use the 2021 semantics of Rust.

Otherwise, all the code, examples, and tests are those of the original author.

Read me

A crate for parsing and using JSON pointers, as specified in RFC 6901. Unlike the pointer method built into serde_json, this handles both validating JSON Pointers before use and the URI Fragment Identifier Representation.

Creating a JSON Pointer

JSON pointers can be created with a literal [&str], or parsed from a String.

let from_strs = JsonPointer::new([
    "foo",
    "bar",
]);
let parsed = "/foo/bar".parse::<JsonPointer<_, _>>().unwrap();
let from_dotted_notation = JsonPointer::new("foo.bar".split('.').collect::<Vec<&str>>());

assert_eq!(from_strs.to_string(), parsed.to_string());

Using a JSON Pointer

The JsonPointer type provides .get() and .get_mut(), to get references and mutable references to the appropriate value, respectively.

let ptr = "/foo/bar".parse::<JsonPointer<_, _>>().unwrap();

let document = json!({
    "foo": {
        "bar": 0,
        "baz": 1,
    },
    "quux": "xyzzy"
});

let indexed = document.get(&ptr).unwrap();

assert_eq!(indexed, &json!(0));

URI Fragment Identifier Representation

JSON Pointers can be embedded in the fragment portion of a URI. This is the reason why most JSON pointer libraries require a # character at the beginning of a JSON pointer. The crate will detect the leading # as an indicator to parse in URI Fragment Identifier Representation. Note that this means that this crate does not support parsing full URIs.

let str_ptr = "/f%o".parse::<JsonPointer<_, _>>().unwrap();
let uri_ptr = "#/f%25o".parse::<JsonPointer<_, _>>().unwrap();

assert_eq!(str_ptr, uri_ptr);