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 identified 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`

Note `/` does not identify the root (i.e., the whole document), but an object entry with empty key `""`. See RFC 6901 for more information.

## 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

- Class `json_pointer`
- Function `flatten`
- Function `unflatten`
- JSON Patch

Last update: June 6, 2022
Back to top