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:

{
  "clients": [
    {
      "name": "Johnny Example",
      "email": "john@example.com",
      "orders": [
          {"address": "Streetroad 123", "price": 103.20},
          {"address": "Streetroad 123", "price": 98.99}
      ]
    },
    {
      "name": "Jane Example",
      "email": "jane@example.com",
      "orders": [
          {"address": "Waypath 321", "price": 22.00},
          {"address": "Streetroad 123", "price": 2330.01}
      ]
    }
  ]
}

In the simplest case JSONPath can replace nested access:

*** Tasks ***
Nested access
    # First order of first client, with direct dictionary access
    ${value}=    Set variable    ${json}["clients"][0]["orders"][0]

    # JSONPath access
    ${value}=    Get value from JSON    ${json}    $.clients[0].orders[0]

But the power comes from complicated expressions:

*** Tasks ***
Complicated expressions
    # Find delivery addresses for all orders
    ${prices}=        Get values from JSON    $..address

    # Find orders that cost over 100
    ${expensives}=    Get values from JSON    $..orders[?(@.price>100)]

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:

*** Task ***
Get genres
    ${genres}=  Get values from JSON    $.books[*].genres.split(,, 0, -1)

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.