RPA.JSON
JSON is a library for manipulating JSON files and strings.
JSON is a common data interchange format inspired by a subset of the Javascript programming language, but these days is a de facto standard in modern web APIs and is language agnostic.
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:
| JSON | Python |
|---|---|
| object | dict |
| array | list |
| string | str |
| number (int) | int |
| number (real) | float |
| true | True |
| false | False |
| null | None |
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.
Syntax example
For this example consider the following structure:
In the simplest case JSONPath can replace nested access:
But the power comes from complicated expressions:
Supported Expressions
The supported syntax elements are:
| Element | Description |
|---|---|
| $ | Root object/element |
| @ | Current object/element inside expressions |
| . or [] | Child operator |
| .. | Recursive descendant operator |
| `parent` | Parent operator, see functions |
| * | Wilcard, any element |
| , | Select multiple fields |
| [n] | Array index |
| [a:b:c] | Array slice (start, end, step) |
| [a,b] | Union of indices or names |
| [?()] | Apply a filter expression |
| () | Script 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 |
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:
| Function | Usage |
|---|---|
| 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 |
Arithmetic Functions
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.
Additional Information
There are a multitude of different script expressions in addition to the elements listed above, which can be seen in the aforementioned article.
For further library usage examples, see the individual keywords.