json.path.read

json.path.read() Function

• Introduced in version 1.5.5

Returns the values in a nested JSON Array or JSON Object corresponding to the provided path. It is unnecessary to include the root node operator $ at the beginning of the requested path. To do so, you must escape the dollar sign like this: \$.path.to.read. The json.path functions support both dot, Monsters.Orc.Attacks, and bracket, ['Monsters']['Orc']['Attacks'], notation. For detailed information on how to specify the path, please read the JsonPath ReadMe.

Usage

json.path.read(json, path)
json.path.read(json, path, config)

Parameters

• json - The json data to get the values from.
• path - The path of the value(s) to retrieve.
• config - A String containing configuration options separated by a comma. The options can include
  • ALWAYS_RETURN_LIST - Always return the results in a JSON Array, even when the path is definite.
  • AS_PATH_LIST - Return a JSON Array of path strings representing the path of the evaluation hits.
  • DEFAULT_PATH_LEAF_TO_NULL - Return null when the given path almost exists but ends with a JSON Object key that is missing. Without this configuration, a definite path will return an error. With this configuration, an indefinite path will include null in the JSON Array if the key is missing. Without this configuration or if any other kind of nonexistent path structure is provided, an indefinite path will simply not match and return an empty JSON Array or less results in the JSON Array.
  • REQUIRE_PROPERTIES - When an indefinite path is evaluated and ends in a key, all matching JSON Objects must have that key, otherwise an error is returned. This are the cases where DEFAULT_PATH_LEAF_TO_NULL will return null instead.
  • SUPPRESS_EXCEPTIONS - Suppress all exceptions when evaluating paths. If ALWAYS_RETURN_LIST is also used return an empty list. Otherwise return null.

See the Jayway javadoc page for more info.

Examples

Suppose we have the following nested json:

[h:troll = json.set("{}", "name", "Troll", "HP", 75, "Attacks", json.append("Claw", "Bite"))]
[h:orc = json.set("{}", "name", "Orc", "HP", 13, "Attacks", json.append("Sword", "Punch"))]
[h:monsters = json.set("{}", "Troll", troll, "Orc", orc)]

To access the value of the first weapon of the Orc, we can type

[json.path.read(monsters, "Orc.Attacks.[0]")]

which returns Sword as a string.

If we instead wanted to return an array with the attacks of every monster, we could type

[r: json.path.read(monsters, ".Attacks")]

which would return [["Claw","Bite"],["Sword","Punch"]]. Starting a path with . will return an array containing the values requested.

Inline filters are also supported, so that if we want the name of the monsters with > 30 HPs, we can type

[r: json.path.read(monsters, ".[?(@.HP > 30)]['name']")]

which returns ["Troll"]. Note the use of bracket notation for the path.

Version Changes

• 1.5.11 - Add config parameter.