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
`/`	`#!json {"array":["A","B","C"],"nested":{"one":1,"two":2,"three":[true,false]}}`
`/array`	`#!json ["A","B","C"]`
`/array/0`	`#!json A`
`/array/1`	`#!json B`
`/array/2`	`#!json C`
`/nested`	`#!json {"one":1,"two":2,"three":[true,false]}`
`/nested/one`	`#!json 1`
`/nested/two`	`#!json 2`
`/nested/three`	`#!json [true,false]`
`/nested/three/0`	`#!json true`
`/nested/three/1`	`#!json 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();

4 KiB Raw Blame History

JSON Pointer

Introduction

JSON Pointer creation

Value access

Flatten / unflatten

See also

4 KiB

Raw Blame History