Add to JSON

Add items into a JSON serializable object and return the result.

Arguments

Argument Type Default value Description
docDict[Hashable, str | int | float | bool | list | dict | None], List[str | int | float | bool | list | dict | None], str, int, float, bool, list, dict, NonenullJSON serializable object
exprstrnullJSONPath expression
valueDict[Hashable, str | int | float | bool | list | dict | None], List[str | int | float | bool | list | dict | None], str, int, float, bool, list, dict, Nonenullvalues to either append or update

If the target is a list, the values are appended to the end. If the target is a dict, the keys are either added or updated.

param doc:JSON serializable object
param expr:JSONPath expression
param value:values to either append or update
return:JSON serializable object of the updated JSON

Robot Framework Example:

*** Task ***
Change the name value for all people
    &{before}=    Convert string to JSON   {"People": [{"Name": "Mark"}, {"Name": "Jane"}]}
    &{person}=    Create dictionary      Name=John
    &{after}=     Add to JSON    ${before}   $.People    ${person}

Python Example:

from RPA.JSON import JSON

# Change the name value for all people
js = JSON()
before = js.convert_string_to_json('{"People": [{"Name": "Mark"}, {"Name": "Jane"}]}')
person = {"Name": "John"}
after = js.add_to_json(before, "$.People", person)

print(after)

Convert JSON to String

Convert a JSON serializable object to a string and return it.

Arguments

Argument Type Default value Description
docDict[Hashable, str | int | float | bool | list | dict | None], List[str | int | float | bool | list | dict | None], str, int, float, bool, list, dict, NonenullJSON serializable object
param doc:JSON serializable object
return:string of the JSON serializable object

Robot Framework Example:

*** Task ***
Convert to string
    ${obj}=    Create dictionary    Key=Value
    ${json}=   Convert JSON to string    ${obj}
    Should be equal    ${json}     {"Key": "Value"}

Python Example:

from RPA.JSON import JSON
from robot.libraries.BuiltIn import BuiltIn

obj = {"Key": "Value"}
json = JSON().convert_json_to_string(obj)
BuiltIn().should_be_equal(json, '{"Key": "Value"}')

Convert String to JSON

Convert a string to a JSON serializable object and return it.

Arguments

Argument Type Default value Description
docstrnullJSON string
param doc:JSON string
return:JSON serializable object of the string

Robot Framework Example:

*** Task ***
Convert to json
    ${json}=    Set variable    {"Key": "Value"}
    &{obj}=     Convert string to JSON    ${json}
    Should be equal    ${obj.Key}    Value

Python Example:

from RPA.JSON import JSON
from robot.libraries.BuiltIn import BuiltIn

json = '{"Key": "Value"}'
obj = JSON().convert_string_to_json(json)
BuiltIn().should_be_equal(obj["Key"], "Value")

Delete from JSON

Delete values from a JSON serializable object and return the result. Will delete all values that match the expression.

Arguments

Argument Type Default value Description
docDict[Hashable, str | int | float | bool | list | dict | None], List[str | int | float | bool | list | dict | None], str, int, float, bool, list, dict, NonenullJSON serializable object or string
exprstrnullJSONPath expression
param doc:JSON serializable object or string
param expr:JSONPath expression
return:JSON serializable object with values removed

Examples

*** Task ***
Delete all people
    &{before}=    Convert string to JSON   {"People": [{"Name": "Mark"}, {"Name": "Jane"}]}
    &{after}=     Delete from JSON    ${before}   $.People[*]
from RPA.JSON import JSON

# Delete all people
before = {"People": [{"Name": "Mark"}, {"Name": "Jane"}]}
after = JSON().delete_from_json(before, "$.People[*]")
print(after)

Get value from JSON

Get a single value from a JSON serializable object that matches the given expression.

Arguments

Argument Type Default value Description
docDict[Hashable, str | int | float | bool | list | dict | None], List[str | int | float | bool | list | dict | None], str, int, float, bool, list, dict, NonenullJSON serializable object or string
exprstrnulljsonpath expression
defaultAny, NoneNonedefault value to return in the absence of a match

Raises a ValueError if there is more than one match. Returns the given default argument (or None) if there were no matches.

param doc:JSON serializable object or string
param expr:jsonpath expression
param default:default value to return in the absence of a match
return:string containing the match OR default if there are no matches
raises ValueError:
 if more than one match is discovered

Short Robot Framework Example:

*** Task ***
Get the name value for the first person
    &{people}=    Convert string to JSON   {"People": [{"Name": "Mark"}, {"Name": "Jane"}]}
    ${first}=     Get value from JSON      ${people}   $.People[0].Name

Short Python Example:

from RPA.JSON import JSON

# Get the name value for the second person.
people = {"People": [{"Name": "Mark"}, {"Name": "Jane"}]}
second = JSON().get_value_from_json(people, "$.People[1].Name")
print(second)

Extended Robot Framework Example:

*** Settings ***
Library         RPA.JSON
Suite Setup     Ingest JSON

*** Variables ***
${JSON_STRING}      {
...                   "clients": [
...                     {
...                       "name": "Johnny Example",
...                       "email": "john@example.com",
...                       "orders": [
...                         {"address": "Streetroad 123", "state": "TX", "price": 103.20, "id":"guid-001"},
...                         {"address": "Streetroad 123", "state": "TX", "price": 98.99, "id":"guid-002"}
...                       ]
...                     },
...                     {
...                       "name": "Jane Example",
...                       "email": "jane@example.com",
...                       "orders": [
...                         {"address": "Waypath 321", "state": "WA", "price": 22.00, "id":"guid-003"},
...                         {"address": "Streetroad 123", "state": "TX", "price": 2330.01, "id":"guid-004"},
...                         {"address": "Waypath 321", "state": "WA", "price": 152.12, "id":"guid-005"}
...                       ]
...                     }
...                   ]
...                 }
${ID}               guid-003

*** Tasks ***
Get email for specific order id
    ${email}=    Get value from json    ${JSON_DOC}    $.clients[?(@..id=="${ID}")].email
    Log    \nOUTPUT IS\n ${email}    console=${True}
    Should be equal as strings    ${email}    jane@example.com

*** Keywords ***
Ingest JSON
    ${doc}=    Convert string to json    ${JSON_STRING}
    Set suite variable    ${JSON_DOC}    ${doc}

Get values from JSON

Get all values from a JSON serializable object that match the given expression.

Arguments

Argument Type Default value Description
docDict[Hashable, str | int | float | bool | list | dict | None], List[str | int | float | bool | list | dict | None], str, int, float, bool, list, dict, NonenullJSON serializable object or string
exprstrnullJSONPath expression
param doc:JSON serializable object or string
param expr:JSONPath expression
return:list of values that match

Short Robot Framework Example:

*** Task ***
Get all the names for all people
    &{people}=    Convert string to JSON   {"People": [{"Name": "Mark"}, {"Name": "Jane"}]}
    @{names}=     Get values from JSON     ${people}   $.People[*].Name

Short Python Example:

from RPA.JSON import JSON

# Get all the names for all people
people = {"People": [{"Name": "Mark"}, {"Name": "Jane"}]}
names = JSON().get_values_from_json(people, "$.People[*].Name")
print(second)

Extended Robot Framework Example:

*** Settings ***
Library         RPA.JSON
Suite Setup     Ingest JSON

*** Variables ***
${JSON_STRING}      {
...                   "clients": [
...                     {
...                       "name": "Johnny Example",
...                       "email": "john@example.com",
...                       "orders": [
...                         {"address": "Streetroad 123", "state": "TX", "price": 103.20, "id":"guid-001"},
...                         {"address": "Streetroad 123", "state": "TX", "price": 98.99, "id":"guid-002"}
...                       ]
...                     },
...                     {
...                       "name": "Jane Example",
...                       "email": "jane@example.com",
...                       "orders": [
...                         {"address": "Waypath 321", "state": "WA", "price": 22.00, "id":"guid-003"},
...                         {"address": "Streetroad 123", "state": "TX", "price": 2330.01, "id":"guid-004"},
...                         {"address": "Waypath 321", "state": "WA", "price": 152.12, "id":"guid-005"}
...                       ]
...                     }
...                   ]
...                 }
${ID}               guid-003

*** Tasks ***
Get All Prices and Order Ids
    # Arithmetic operations only work when lists are of equal lengths and types.
    ${prices}=    Get values from json
    ...    ${JSON_DOC}
    ...    $.clients[*].orders[*].id + " has price " + $.clients[*].orders[*].price.`str()`
    Log    \nOUTPUT IS\n ${prices}    console=${True}
    Should be equal as strings    ${prices}
    ...    ['guid-001 has price 103.2', 'guid-002 has price 98.99', 'guid-003 has price 22.0', 'guid-004 has price 2330.01', 'guid-005 has price 152.12']

Find Only Valid Emails With Regex
    # The regex used in this example is simplistic and
    # will not work with all email addresses
    ${emails}=    Get values from json
    ...    ${JSON_DOC}
    ...    $.clients[?(@.email =~ "[a-zA-Z]+@[a-zA-Z]+\.[a-zA-Z]+")].email
    Log    \nOUTPUT IS\n ${emails}    console=${True}
    Should be equal as strings    ${emails}    ['john@example.com', 'jane@example.com']

Find Orders From Texas Over 100
    # The regex used in this example is simplistic and
    # will not work with all email addresses
    ${orders}=    Get values from json
    ...    ${JSON_DOC}
    ...    $.clients[*].orders[?(@.price > 100 & @.state == "TX")]
    Log    \nOUTPUT IS\n ${orders}    console=${True}
    Should be equal as strings    ${orders}
    ...    [{'address': 'Streetroad 123', 'state': 'TX', 'price': 103.2, 'id': 'guid-001'}, {'address': 'Streetroad 123', 'state': 'TX', 'price': 2330.01, 'id': 'guid-004'}]


*** Keywords ***
Ingest JSON
    ${doc}=    Convert string to json    ${JSON_STRING}
    Set suite variable    ${JSON_DOC}    ${doc}

Load JSON from file

Load JSON data from a file, and return it as JSON serializable object. Depending on the input file the object can be either a dictionary, a list, or a scalar value.

Arguments

Argument Type Default value Description
filenamestrnullpath to input file
encodingutf-8file character encoding
param filename:path to input file
param encoding:file character encoding
return:JSON serializable object of the JSON file

Examples

*** Task ***
Load json
    &{auth}=    Load JSON from file    auth.json
    Log   Current auth token: ${auth.token}

Save JSON to file

Save a JSON serializable object or a string containing a JSON value into a file.

Arguments

Argument Type Default value Description
docDict[Hashable, str | int | float | bool | list | dict | None], List[str | int | float | bool | list | dict | None], str, int, float, bool, list, dict, NonenullJSON serializable object or string
filenamestrnullpath to output file
indentint, NoneNoneif given this value is used for json file indent
encodingstrutf-8file character encoding
param doc:JSON serializable object or string
param filename:path to output file
param indent:if given this value is used for json file indent
param encoding:file character encoding

Robot Framework Example:

*** Tasks ***
Save dictionary to file
    ${john}=    Create dictionary    name=John    mail=john@example.com
    Save JSON to file    ${john}    john.json

Save string to file
    ${mark}=    Set variable    {"name": "Mark", "mail": "mark@example.com"}
    Save JSON to file    ${mark}    mark.json

Python Example:

from RPA.JSON import JSON

# Save dictionary to file.
john = {"name": "John", "mail": "john@example.com"}
JSON().save_json_to_file(john, "john.json")

Update value to JSON

Update existing values in a JSON serializable object and return the result. Will change all values that match the expression.

Arguments

Argument Type Default value Description
docDict[Hashable, str | int | float | bool | list | dict | None], List[str | int | float | bool | list | dict | None], str, int, float, bool, list, dict, NonenullJSON or string
exprstrnullJSONPath expression
valueDict[Hashable, str | int | float | bool | list | dict | None], List[str | int | float | bool | list | dict | None], str, int, float, bool, list, dict, NonenullNew value for the matching item(s)
param doc:JSON or string
param expr:JSONPath expression
param value:New value for the matching item(s)
return:JSON serializable object with updated results

Short Robot Framework Example:

*** Tasks ***
Change the name key for all people
    &{before}=    Convert string to JSON   {"People": [{"Name": "Mark"}, {"Name": "Jane"}]}
    &{after}=     Update value to JSON     ${before}   $.People[*].Name    JohnMalkovich
from RPA.JSON import JSON

# Change the name key for all people
before = {"People": [{"Name": "Mark"}, {"Name": "Jane"}]}
after = JSON().update_value_to_json(before, "$.People[*].Name","JohnMalkovich")
print(after)

Extended Robot Framework Example:

*** Settings ***
Library         RPA.JSON
Library    Collections
Suite Setup     Ingest JSON

*** Variables ***
${JSON_STRING}      {
...                   "clients": [
...                     {
...                       "name": "Johnny Example",
...                       "email": "john@example.com",
...                       "id": "user-001",
...                       "orders": [
...                         {"address": "Streetroad 123", "state": "TX", "price": 103.20, "id":"guid-001"},
...                         {"address": "Streetroad 123", "state": "TX", "price": 98.99, "id":"guid-002"}
...                       ]
...                     },
...                     {
...                       "name": "Jane Example",
...                       "email": "jane@example.com",
...                       "id": "user-002",
...                       "orders": [
...                         {"address": "Waypath 321", "state": "WA", "price": 22.00, "id":"guid-003"},
...                         {"address": "Streetroad 123", "state": "TX", "price": 2330.01, "id":"guid-004"},
...                         {"address": "Waypath 321", "state": "WA", "price": 152.12, "id":"guid-005"}
...                       ]
...                     }
...                   ]
...                 }
${ID}               guid-003

*** Tasks ***
Update user email
    ${updated_doc}=    Update value to json
    ...    ${JSON_DOC}
    ...    $.clients[?(@.id=="user-001")].email
    ...    johnny@example.com
    Log    \nNEW JSON IS\n ${updated_doc}    console=${True}
    ${new_email}=    Get value from json    ${updated_doc}    $.clients[?(@.id=="user-001")].email
    Should be equal as strings    ${new_email}    johnny@example.com

Add additional charge to all prices in WA
    # This example also shows how the update keyword changes the original JSON doc in memory.
    ${id_price}=    Get values from json
    ...    ${JSON_DOC}
    ...    $.clients[*].orders[?(@.state=="WA")].id,price
    FOR    ${order_id}    ${price}    IN    @{id_price}
        Update value to json    ${JSON_DOC}    $.clients[*].orders[?(@.id=="${order_id}")].price    ${{${price} * 1.06}}
    END
    Log    \nNEW JSON IS\n ${JSON_DOC}    console=${True}
    ${one_price}=    Get value from json    ${JSON_DOC}    $..orders[?(@.id==${ID})].price
    Should be equal as numbers    ${one_price}    23.32

*** Keywords ***
Ingest JSON
    ${doc}=    Convert string to json    ${JSON_STRING}
    Set suite variable    ${JSON_DOC}    ${doc}