Skip to content

JSON Pointer

Introduction

The library supports JSON Pointer (RFC 6901) as alternative means to address structured values. A JSON Pointer is a string that identifies a specific value withing a JSON document.

Consider the following JSON document

{
    "array": ["A", "B", "C"],
    "nested": {
        "one": 1,
        "two": 2,
        "three": [true, false]
    }
}

Then every value inside the JSON document can be idientified as follows:

JSON Pointer JSON value
/ {"array":["A","B","C"],"nested":{"one":1,"two":2,"three":[true,false]}}
/array ["A","B","C"]
/array/0 A
/array/1 B
/array/2 C
/nested {"one":1,"two":2,"three":[true,false]}
/nested/one 1
/nested/two 2
/nested/three [true,false]
/nested/three/0 true
/nested/three/1 false

JSON Pointer creation

JSON Pointers can be created from a string:

json::json_pointer p = "/nested/one";

Furthermore, a user-defined string literal can be used to achieve the same result:

auto p = "/nested/one"_json_pointer;

The escaping rules of RFC 6901 are implemented. See the constructor documentation for more information.

Value access

JSON Pointers can be used in the at, operator[], and value functions just like object keys or array indices.

// the JSON value from above
auto j = json::parse(R"({
    "array": ["A", "B", "C"],
    "nested": {
        "one": 1,
        "two": 2,
        "three": [true, false]
    }
})");

// access values
auto val = j["/"_json_pointer];                             // {"array":["A","B","C"],...}
auto val1 = j["/nested/one"_json_pointer];                  // 1
auto val2 = j.at[json::json_pointer("/nested/three/1")];    // false
auto val3 = j.value[json::json_pointer("/nested/four", 0)]; // 0

Flatten / unflatten

The library implements a function flatten to convert any JSON document into a JSON object where each key is a JSON Pointer and each value is a primitive JSON value (i.e., a string, boolean, number, or null).

// the JSON value from above
auto j = json::parse(R"({
    "array": ["A", "B", "C"],
    "nested": {
        "one": 1,
        "two": 2,
        "three": [true, false]
    }
})");

// create flattened value
auto j_flat = j.flatten();

The resulting value j_flat is:

{
  "/array/0": "A",
  "/array/1": "B",
  "/array/2": "C",
  "/nested/one": 1,
  "/nested/two": 2,
  "/nested/three/0": true,
  "/nested/three/1": false
}

The reverse function, unflatten recreates the original value.

auto j_original = j_flat.unflatten();

See also


Last update: May 1, 2022
Back to top