sjson
- Last UpdatedSep 05, 2024
- 4 minute read
This topic is about the SJSON data type.
Value syntax
SJSON contains a valid JSON string and can be considered a special form of sstring whose content respects the JSON standard specifications.
If you take the string inside an SJSON type field and paste it into any JSON validator, the result should be a green light from the validator, meaning that the string is compliant with the JSON standard specifications.
For this reason, assigning a string that does not comply with the JSON standard to an SJSON field would result in an exception.
XRJPATH syntax
SJSON uses in its attributes a special syntax that we will call XRJPATH syntax. With this syntax, it is possible to retrieve values from SJSON elements of the supported types.
The XRJPATH syntax allows referencing to specific elements in the data tree structure by using the | symbol as a separator.
-
A single | represents the root of the json.
-
Elements are referenced as a pipe-separated list of keys starting from the root.
-
Values inside Array elements can be accessed by specifying the element key followed by the desired index inside parenthesis (round brackets).
Example
Let’s take this example SJSON value.
{
"object": {
"value": "a string value"
},
"array": ["value", ["arrayValue"], {
"objectValue": "object value"
}],
"string": "a string",
"integer": 1,
"boolean": true,
"float": 1.5
}
To reference the integer element, the correct XRJPATH would be: |integer
To reference the second element of the array element value, the correct XRJPATH would be: |array(1)
To reference the objectValue inside the third element or array the correct XRJPATH would be: |array(2)|objectValue
Element types
The SJSON data type represents a JSON object and provides the means to read and manipulate JSON data, whether it comes from external inputs or is defined inside the script logic itself. SJSON supports three type of elements.
|
Element type |
Description |
|---|---|
|
obj |
A JSON container, the root itself is of this type, value is enclosed by curly brackets. |
|
array |
A list of elements of any type, value is enclosed by square brackets. |
|
value |
A value, that can be of any subtype among string, integer, float, or boolean. |
SJSON does not support comments, or any other element types different than obj, array, or value.
Var of type SJSON can be declared in the script file in the standard way or inline.
Be aware that using the standard declaration has strong limitations due to XML reserved characters, especially double quotation marks.
<!-- Standard Declaration -->
<Var name="myJson" type="sjson" value="{ 'a value name': 'the value' }" />
<!-- In-line Declaration -->
<Var name="inlineJson" type="sjson">
{
"object": {
"value": "a string value"
},
"array": [ "value", ["arrayValue"], {"objectValue": "object value"}],
"string": "a string",
"integer": 1,
"boolean": true,
"float": 1.5
}
</Var>
Attributes
These are the attributes for SJSON.
|
Attribute |
Type |
Description |
|---|---|---|
|
exists(XRJPATH) |
sbool |
Returns True if the specified XRJPATH corresponds to a key inside the SJSON value and False if otherwise. |
|
findElement(KEY_NAME) |
sbool |
Returns the XRJPATH of the first element in the SJSON with name corresponding to the provided KEY_NAME. If no matching element is found, an empty string is returned. |
|
getArrayLength(XRJPATH) |
sint |
Returns the length of array element value. If the specified XRJPATH corresponds to an element of a different type than array it returns -1. |
|
getChildren(XRJPATH) |
mstring |
Returns the list of children keys of the specified XRJPATH obj element. If the specified XRJPATH corresponds to a different type than obj, an empty list is returned. |
|
getObject(JSONPATH) |
sjson |
Returns an SJSON corresponding to the specified JSONPATH element of type obj. Keep in mind that this method uses the standard JSONPATH syntax and not XRJPATH. For further information on the JSONPATH syntax, please refer to online documentation: https://stackoverflow.com/tags/jsonpath/info |
|
getType(XRJPATH) |
sstring |
Returns the type of the referenced key element. Types returned can be obj, array, or value. |
|
getValue(XRJPATH) |
sstring |
Returns the value of the specified XRJPATH value element. Even if values in a JSON document are of different type, this method will always return a SSTRING value. It is up to the user to eventually parse and cast the SSTRING to a different field data type in their code whenever it is required. |
|
addObject(XRJPATH,KEY_NAME) |
sjson |
Returns a modified copy of the SJSON. Adds an element of type obj as a child of the specified XRJPATH element and with the key corresponding to the specified KEY_NAME. In cases where XRJPATH references an element of type array the KEY_NAME is ignored and can be omitted. |
|
addArray(XRJPATH,KEY_NAME) |
sjson |
Returns a modified copy of the SJSON. Adds an element of type array as a child of the specified XRJPATH element and with the key corresponding to the specified KEY_NAME. In cases where XRJPATH references an element of type array, the KEY_NAME is ignored and can be omitted. |
|
addValue(XRJPATH,KEY_NAME,VALUE_TYPE) |
sjson |
Returns a modified copy of the SJSON. Adds an element of type value as a child of the specified XRJPATH element and with the key corresponding to the specified KEY_NAME. It sets the value to the default of its value type. VALUE_TYPE is optional. If not specified, or if set to an unsupported value type, the string is used as a default. Supported VALUE_TYPEs are string, integer, float, boolean. In cases where XRJPATH references an element of type array, the KEY_NAME is ignored and can be omitted. |
|
rem(XRJPATH) |
sjson |
Returns a modified copy of the SJSON. Removes the element corresponding to the specified XRJPATH. |
|
setValue(XRJPATH,VALUE,VALUE_TYPE) |
sjson |
Returns a modified copy of the SJSON. Sets the value of the specified XRJPATH element of value type to VALUE. VALUE_TYPE is an optional parameter and it can be set as string, integer, float, or boolean. If it is not specified, the current value type of the element is preserved. |