JSON-GLib Reference Manual: JsonPath

## JsonPath JsonPath — JSONPath implementation |

## Functions

JsonPath * | json_path_new ()
#define | JSON_PATH_ERROR
gboolean | json_path_compile ()
JsonNode * | json_path_match ()
JsonNode * | json_path_query ()

## Types and Values

| JsonPath
| JsonPathClass
enum | JsonPathError

## Object Hierarchy

        GObject
        ╰── JsonPath

## Description

JsonPath is a simple class implementing the JSONPath syntax for extracting data out of a JSON tree. While the semantics of the JSONPath expressions are heavily borrowed by the XPath specification for XML, the syntax follows the ECMAScript origins of JSON.

Once a JsonPath instance has been created, it has to compile a JSONPath expression using `json_path_compile()` before being able to match it to a JSON tree; the same JsonPath instance can be used to match multiple JSON trees. It it also possible to compile a new JSONPath expression using the same JsonPath instance; the previous expression will be discarded only if the compilation of the new expression is successful.

The simple convenience function `json_path_query()` can be used for one-off matching.

#### Syntax of the JSONPath expressions

A JSONPath expression is composed by path indices and operators. Each path index can either be a member name or an element index inside a JSON tree. A JSONPath expression must start with the '$' operator; each path index is separated using either the dot notation or the bracket notation, e.g.:

    1
    2
    3
    4
    5
    // dot notation
    $.store.book[0].title

    // bracket notation
    $['store']['book'][0]['title']

The available operators are:

- Root node The '$' character represents the root node of the JSON tree, and matches the entire document.

- Child nodes can either be matched using '.' or '[]'. For instance, both `$.store.book` and `$'store' match the contents of the book member of the store object.

- Child nodes can be reached without specifying the whole tree structure through the recursive descent operator, or '..'. For instance, `$..author` matches all author member in every object.

- Child nodes can grouped through the wildcard operator, or '*'. For instance, `$.store.book[*].author` matches all author members of any object element contained in the book array of the store object.

- Element nodes can be accessed using their index (starting from zero) in the subscript operator '[]'. For instance, `$.store.book[0]` matches the first element of the book array of the store object.

- Subsets of element nodes can be accessed using the set notation operator '[start,end]'. For instance, `$.store.book[0,2]` matches the first, second, and third elements of the book array of the store object.

- Slices of element nodes can be accessed using the slice notation operation '[start:end:step]'. If start is omitted, the starting index of the slice is implied to be zero; if end is omitted, the ending index of the slice is implied to be the length of the array; if step is omitted, the step of the slice is implied to be 1. For instance, `$.store.book[:2]` matches the first two elements of the book array of the store object.

More information about JSONPath is available on Stefan Gössner's JSONPath website.

#### Example of JSONPath matches

The following example shows some of the results of using JsonPath on a JSON tree. We use the following JSON description of a bookstore:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    { "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" }
      }
    }

We can parse the JSON using JsonParser:

    1
    2
    JsonParser *parser = json_parser_new ();
    json_parser_load_from_data (parser, json_data, -1, NULL);

If we run the following code:

    1
    2
    3
    4
    JsonNode *result;
    JsonPath *path = json_path_new ();
    json_path_compile (path, "$.store..author", NULL);
    result = json_path_match (path, json_parser_get_root (parser));

The result JsonNode will contain an array with all values of the author member of the objects in the JSON tree. If we use a JsonGenerator to convert the JsonNode to a string and print it:

    1
    2
    3
    4
    JsonGenerator *generator = json_generator_new ();
    json_generator_set_root (generator, result);
    char *str = json_generator_to_data (generator, NULL);
    g_print ("Results: %s\n", str);

The output will be:

    1
    ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"]

JsonPath is available since JSON-GLib 0.14

## Functions

### json_path_new ()

    JsonPath *
    json_path_new (void);

Creates a new JsonPath instance.

Once created, the JsonPath object should be used with `json_path_compile()` and `json_path_match()`.

#### Returns

the newly created JsonPath instance. Use `g_object_unref()` to free the allocated resources when done.

[transfer full]

Since 0.14

### JSON_PATH_ERROR

    #define JSON_PATH_ERROR         (json_path_error_quark ())

Error domain for JsonPath errors

Since 0.14

### json_path_compile ()

    gboolean
    json_path_compile (JsonPath *path,
                       const char *expression,
                       GError **error);

Validates and decomposes `expression` .

A JSONPath expression must be compiled before calling `json_path_match()`.

#### Parameters

path | a JsonPath |
expression | a JSONPath expression |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success; on error, `error` will be set with the `JSON_PATH_ERROR` domain and a code from the JsonPathError enumeration, and `FALSE` will be returned

Since 0.14

### json_path_match ()

    JsonNode *
    json_path_match (JsonPath *path,
                     JsonNode *root);

Matches the JSON tree pointed by `root` using the expression compiled into the JsonPath.

The matching JsonNodes will be copied into a JsonArray and returned wrapped in a JsonNode.

#### Parameters

path | a compiled JsonPath |
root | a JsonNode |

#### Returns

a newly-created JsonNode of type `JSON_NODE_ARRAY` containing an array of matching JsonNodes. Use `json_node_free()` when done.

[transfer full]

Since 0.14

### json_path_query ()

    JsonNode *
    json_path_query (const char *expression,
                     JsonNode *root,
                     GError **error);

Queries a JSON tree using a JSONPath expression.

This function is a simple wrapper around `json_path_new()`, `json_path_compile()` and `json_path_match()`. It implicitly creates a JsonPath instance, compiles `expression` and matches it against the JSON tree pointed by `root` .

#### Parameters

expression | a JSONPath expression |
root | the root of a JSON tree |
error | return location for a GError, or `NULL` |

#### Returns

a newly-created JsonNode of type `JSON_NODE_ARRAY` containing an array of matching JsonNodes. Use `json_node_free()` when done.

[transfer full]

Since 0.14

## Types and Values

### JsonPath

    typedef struct _JsonPath JsonPath;

The `JsonPath` structure is an opaque object whose members cannot be directly accessed except through the provided API.

Since 0.14

### JsonPathClass

    typedef struct _JsonPathClass JsonPathClass;

The `JsonPathClass` structure is an opaque object class whose members cannot be directly accessed.

Since 0.14

### enum JsonPathError

Error code enumeration for the `JSON_PATH_ERROR` domain.

#### Members

JSON_PATH_ERROR_INVALID_QUERY | Invalid query |

Since 0.14