JSON expressions

This topic describes JSON expressions used in Robots.

JSON expressions consist of:

• Numbers

• Booleans

• Strings

• Constant, null

• Objects

• Arrays

You can write null, objects, and arrays directly in an expression, and all other forms, inside objects and arrays. This means that a number written alone, such as 1, is considered to have type number, but a number written inside an object, such as {"name": "Joe", "age": 42}, is considered to have type JSON. The same is true for booleans and strings. However, it is possible to directly assign a value of simple type to a JSON variable, such as a number, a boolean, or a text.

You can use variables or even expressions inside a JSON expression, such as [x, y+1] or {"a": x*y}. This means that it is possible to create JSON from an expression that functions as a template. Example: {"name": name, "age": age, "title": title}, where name, age, and title are variables.

JSON expression syntax may be mixed with normal expressions in any possible way. For example, you can write an expression, such as {"a": x > y ? [x, y] : [y, x]}, which has a conditional expression inside an object expression, and an array expression inside the conditional expression.

However, there are some exceptions. A JSON value cannot appear at a position where we expect a value of another type than JSON. But number, integer, text, and boolean values may always appear where a JSON value is expected. For example, it is not possible to add a JSON number to number: If json is a variable of JSON type that contains a number and we want to add it to an integer 5, it is not possible to write json + 5, because we are not sure that the variable always contains a number or an integer. Instead, you should write json.integer() + 5. Thus, we announce that we expect that the value in the json variable is an integer. If it is different, the robot throws an exception.

There are various JSON expressions that may be used within normal expressions:

• The object creation expression, such as {}, {"a": 5}

• The array creation expression, such as [], [1, 2, 3]

• The constant, null

Also, there are other extensions of the expression language introduced by the JSON type:

• The array access expression expr[expr], where the first expr is any expression of type JSON and the second expr is an integer expression.

  For example, expression [1,2,3][1] evaluates to 2. Because elements of an array have zero-based indices, the element with the index 1 is the second element in the array.

  Also, if the first expr is an object value and the second expr is a text value, the expression is accessing the value of a key of the object. For example, expression {"a": 5}["a"] evaluates to 5. This form is equivalent to a field access, such as {"a": 5}.a, but because keys in JSON can be any string, there might be cases where field access cannot be used to access the value of a key in a JSON object. For example, you can use {"a.b": 5}["a.b"], but you cannot use {"a.b": 5"}.a.b.

  Another use of the expression is when the key is computed, such as the value of a variable. For example, {"a": 5}[v], where v is a text variable.

• The field access expression expr.id, where expr is an expression evaluating to a JSON object value and id is a key (identifier). If the value is not a JSON object, an exception is thrown.

  For example: {"a": 5}.a.

• The object override expression. If the object creation expression is placed after an expression of type JSON, all the key/value pairs in the object creation expression override the ones in the JSON expression.

  For example, {"a": 5}{"a": 7, "b": true} evaluates to {"a": 7, "b": true}.

  Thus, the object override expression can both override the value of a key "a" and add a new key/value pair "b": true.

• The array override expression. This expression is similar to the object override expression, except that it can only override existing elements in an array.

  For example: [true, false, null][1: 42] evaluates to [true, 42, null], overriding the element in the array at index 1.

• The convert object to record expression. This expression creates a new record value with the values of the keys on a JSON object overriding the corresponding fields of the record.

  For example, r{json}, where r is a record variable and json is a JSON object. This expression creates a new record value with the value of the fields in r overridden with the values of the corresponding keys in the JSON object.

• Equality expressions == and != are allowed for JSON values. Two objects are equal if they have the same key/value pairs. The order they are displayed does not matter.

  Syntax	Description	Example
  expr[expr]	Access	[1,2,3][1] evaluates to 2
  expr.id	Access	{"a": 5}.a evaluates to 5 (the JSON value 5)
  expr == expr	Equality	[1,2] == [1,2] evaluates to true
  expr != expr	Inequality	[] != [1,2] evaluates to true
  null	The null data type in JSON	null evaluates to null
  {"id": expr,…}	Creates a new JSON object	{"a": 5, "b": true}
  expr{"id": expr,…}	Overrides and/or adds key/value pairs in a JSON object	If variable json = {"a": 5, "c": null}, json{"a": 7, "b": true} evaluates to {"a": 7, "b": true, "c": null}
  expr{expr}	Creates a new Record value with the values of the keys in a JSON object overriding the corresponding fields of the record. This is a quick way to turn a JSON object into a Record value. The set of keys in the JSON object must be a subset of the set of fields in the Record type. If the JSON value contains a key that does not correspond to a field in the Record value, an error is thrown. The JSON object does not have to contain keys for all the fields in the Record value.	r{json} evaluates to R("a": 42), if r is of type R with a field called a and json is a JSON variable with value {"a": 42}
  [expr,…]	Creates a new JSON array	[1, true, null, {}]
  expr[expr:expr,…]	Overrides elements in a JSON array	If variable json = [1, true, null], json[1:false] evaluates to [1, false, null]