JSON is a library for manipulating JSON files and strings.
The term serialization refers to the process of converting Robot Framework or Python types to JSON or the other way around.
Basic types can be easily converted between the domains, and the mapping is as follows:
Reading and writing values from/to JSON serializable objects is done using JSONPath. It's a syntax designed to quickly and easily refer to specific elements in a JSON structure. The specific flavor used in this library is based on jsonpath-ng.
Compared to Python's normal dictionary access, JSONPath expressions can target multiple elements through features such as conditionals and wildcards, which can simplify many JSON-related operations. It's analogous to XPath for XML structures.
For this example consider the following structure:
In the simplest case JSONPath can replace nested access:
But the power comes from complicated expressions:
The supported syntax elements are:
|@||Current object/element inside expressions|
|. or ||Child operator|
|..||Recursive descendant operator|
|`parent`||Parent operator, see functions|
|*||Wilcard, any element|
|,||Select multiple fields|
|[a:b:c]||Array slice (start, end, step)|
|[a,b]||Union of indices or names|
|[?()]||Apply a filter expression|
|[\\field]||Sort descending by field, cannot be combined with filters.|
|[/field]||Sort ascending by field, cannot be combined with filters.|
|`str()`||Convert value to string, see functions|
|`sub()`||Regex substitution function, see functions|
|`len`||Calculate value's length, see functions|
|`split()`||String split function, see functions|
|+ - * /||Arithmetic functions, see functions|
This library allows JSON path expressions to include certain functions which can provide additional benefit to users. These functions are generally encapsulated in backticks (`). Some functions require you to pass arguments similar to a Python function.
For example, let's say a JSON has nodes on the JSON path $.books[*].genres which are represented as strings of genres with commas separating each genre. So for one book, this node might have a value like horror,young-adult. You can return a list of first genre for each book by using the split function like so:
Each functions parameters are defined here:
|str()||No parameters, but parenthesis are required|
|sub(/regex/, repl)||The regex pattern must be provided in regex and the replacement value provided in repl|
|len||No parameters and no parenthesis|
|split(char, segment, max_split)||Separator character provided as char, which index from the resulting array to be returns provided as segment, and maximum number of splits to perform provided as max_split, -1 for all splits.|
|parent||No parameters, no parenthesis|
JSON Path can be written and combined to concatenate string values or perform arithmetic functions on numerical values. Each JSONPath expression used must return the same type, and when performing such functions between returned lists, each list must be the same length. An example is included in documentation for the keyword Get values from JSON.