Functions for Handling JSON Data

General Remarks

JSON support was built into the scripting language because JSON is a common way of exchanging data across a wide range of applications. Virtually anything can be packaged into a JSON object. While some may prefer XML, the overhead of JSON is smaller than that of XML, and it has a (though rudimentary) type system.

The terms “JSON value” and “JSON object” are used almost interchangeably in this page, although, strictly speaking, a JSON object is a special type of value. A value can be a number, a string, a boolean value, an array, or a null value, or an object. A JSON object – enclosed in curly braces {...} – contains properties which have names and values. A property value in itself, again, can be any type, even another object.

JSON pointers are for JSON what XPath s for XML: A way to describe a node within a given JSON value or object. A good introduction to JSON pointers can be found at https://rapidjson.org/md_doc_pointer.html.

JSON values are passed into and out of these scripting functions as strings. Be aware that in JSON, unlike XML, property names and string values must be enclosed in double quotation marks ("..."). Missing quotation marks make a JSON object invalid.

json_Get function

Retrieves a value from a JSON value.

Synopsis

CODE

%value = json_Get(json, pointer, raw)

Parameters

Name	Required?	Type	Documentation
`json`	yes	string	A JSON value
`pointer`	yes	string	The JSON pointer which describes the path to the value to retrieve
`raw`	no	string	(see below)

Returns

The value that is stored in the json at the location described by pointer. The returned value is a valid JSON value, with the following exception:

If the raw parameter is present and has the value RAW in any combination of upper and lower characters, and pointer describes a string value, then this function returns this string value as is, without surrounding quotation marks; in this case, the return value is not a valid JSON value.

json_GetArraySize function

Returns the size (number of elements) of a JSON array.

Synopsis

CODE

%size = json_GetArraySize(%json)

Parameters

Name	Required?	Type	Documentation
`json`	yes	string: JSON value	A JSON value

Returns

If json is a JSON array, the function returns the number of elements in the array.
Otherwise, it returns the value -1.

json_GetType function

Returns the type of a JSON value.

Synopsis

CODE

%type = json_GetType(json, pointer)

Parameters

Name	Required?	Type	Documentation
`json`	yes	string	The value whose type should be retrieved
`pointer`	no	string	If specified, selects a value inside the JSON value.

If the pointer parameter is not specified, the operation refers to the specified json. If pointer is specified, it must be a valid JSON pointer which describes the portion of the json value to which the operation should refer.

Returns

A JSON object with the field “type” describing the data type, and additional fields describing the type more precisely.

“type” field	Additional fields	Example
`"null"`	none	`{"type": "null"}`
`"number"`	`"category": "fixed_point"` or `"floating_point"` `"precision"`: `32` or `64` `"signed": true` or `false` (only for `"category": "fixed_point"`)	`{"type": "number", "category": "fixed_point", "signed": true, "precision": 32}` `{"type": "number", "category": "floating_point", "precision": 64}`
`"bool"`	none	`{"type": "bool"}`
`"string"`	none	`{"type": "string"}`
`"object"`	none	`{"type": "object"}`
`"array"`	`"size"`: (number of array elements)	`{"type": "array", "size": 5}`

json_IsNumber function

Finds out whether a JSON value is a number.

Synopsis

CODE

%is_number = json_IsNumber(17) // result: 1
%is_number = json_IsNumber("Hello world") // result: 0

Parameters

Name	Required?	Type	Documentation
`json`	yes	string	A JSON value
`pointer`	no	string	The JSON pointer which describes the path to the value

Returns

1 if the value is a number, and 0 otherwise.

Remarks

If pointer is not specified or is an empty string, the json_IsNumber function examines the value from the json parameter; otherwise, it examines the value inside json to which pointer points.

json_PrettyPrint function

Reformats a JSON object for better readability.

Synopsis

CODE

%json = json_PrettyPrint(%json)

Parameters

Name	Required?	Type	Documentation
`json`	yes	string	The JSON object

Returns

A string that contains the same JSON object as the json parameter, but formatted with whitespace and line breaks.

json_Set function

Adds or changes a field in a JSON construct. This is the method of your choice to create a JSON value or object, unless you prefer to fiddle with quotation marks and curly braces.

Synopsis

CODE

%json = json_Set("", "", "", object) // result: {}
%json = json_Set(%json, "/name", "data"") // result: {"name": "data"}
%json = json_Set(%json, "/values/0", \{{{"one": 1, "two": 2}\}}) // result: {"name": "data", "values": [{"one": 1, "two": 2}]}
%json = json_Set(%json, "/values/-", 123, string) // result: {"name": "data", "values": [{"one": 1, "two": 2}, "123"]}
%json = %json_Set(%json, "/name") // result: {"values": [{"one": 1, "two": 2}, "123"]}

Line 1 starts with an empty object (first parameter) and sets its root (second parameter) to empty (third parameter), but enforces the type “object”. This returns a JSON value that is an empty object.

Line 2 starts with the empty object of the previous line, and adds a member with name "name" and value "data". The value is automatically recognized as string.

Line 3 takes the object of the previous line and adds a member with the name "values" which is an array whose first item contains the object {"one": 1, "two": 2}. The second parameter contains the number 0 which indicates that it refers to an array index, and the array, which does not exist so far, is implicitly created. The item to be stored in the first array element (index 0) is described in JSON object syntax. Note the use of the special quote syntax \{{ ... \}} which allows to use curly braces and double quotation marks in a string.

Line 4 adds another item to the array "values". The dash at the end of the second parameter stands for "past the current end of the array". The item is specified as 123, which is an integer value, but the fourth parameter forces it to be stored as a string.

Line 5 erases the "name" property with its value.

Parameters

Name	Required?	Type	Documentation
`json`	yes	string	Either an empty string, or a JSON statement that should be modified.
`pointer`	yes	string	Either an empty string (if the root of the JSON statement should be replaced), or a JSON pointer to the place where data should be added or replaced.
`value`	no	any	The data to add or set. Allowed values and their interpretation depends on the data type. When `value` is not present, the node to which `pointer` points is erased if it exists.
`type`	no	string	A JSON data type. If empty or not present, the type is deducted from the data.

A documentation of JSON pointers is available here: https://gregsdennis.github.io/Manatee.Json/usage/pointer.html.

Valid data types are:

Data type	Allowed values	Special notes
`null`	`null`	Empty string is also ok
`number`	integer or floating-point number in decimal notation, with optional leading plus or minus sign	Empty string creates 0
`bool`	one of these strings: `true` `T` `yes` `Y` `false` `F` `no` `N`, or an integer number	Empty string interpreted as false Integer numeric value interpreted as false if `0`, and as true otherwise
`string`	Any character string
`object`	JSON object, enclosed in curly braces `{ ... }`	Empty string creates an empty object
`array`	JSON array, enclosed in square brackets `[ ... ]`	Empty string creates an empty array

If the data type is not explicitly specified, it is deducted from the data value like this:

Value	Deducted type
`null`	`null`
`true` `T` `yes` `Y` `false` `F` `no` `N`	`bool`
numeric value	`number`
JSON object	`object`
JSON array	`array`
anything else	`string`

Returns

The modified JSON value.