json.path.read: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
No edit summary |
||
Line 17: | Line 17: | ||
{{param|path|The path of the value(s) to retrieve.}} | {{param|path|The path of the value(s) to retrieve.}} | ||
{{param|config|A String containing configuration options separated by a comma. The options can include | {{param|config|A String containing configuration options separated by a comma. The options can include | ||
** {{code|ALWAYS_RETURN_LIST}} - Always return the results in a [[JSON Array]]. | ** {{code|ALWAYS_RETURN_LIST}} - Always return the results in a [[JSON Array]], even when the path is definite. | ||
** {{code|AS_PATH_LIST}} - Return a | ** {{code|AS_PATH_LIST}} - Return a JSON Array of path strings representing the path of the evaluation hits. | ||
** {{code|DEFAULT_PATH_LEAF_TO_NULL}} - Return null | ** {{code|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. | ||
** {{code|REQUIRE_PROPERTIES}} - | ** {{code|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. | ||
** {{code|SUPPRESS_EXCEPTIONS}} - Suppress all exceptions when evaluating paths. | ** {{code|SUPPRESS_EXCEPTIONS}} - Suppress all exceptions when evaluating paths. If ALWAYS_RETURN_LIST is also used return an empty list. Otherwise return null. | ||
See the [https://www.javadoc.io/doc/com.jayway.jsonpath/json-path/2.0.0/com/jayway/jsonpath/Option.html Jayway javadoc page] for more info. | See the [https://www.javadoc.io/doc/com.jayway.jsonpath/json-path/2.0.0/com/jayway/jsonpath/Option.html Jayway javadoc page] for more info. | ||
}} | }} |
Revision as of 15:50, 2 May 2021
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 includeALWAYS_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:
which returns
[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']")]
["Troll"]
. Note the use of bracket notation for the path.Version Changes
- 1.5.11 - Add
config
parameter.