JSON data is a simple, lightweight, text format that is self-describing and easy to comprehend. The JSON Extender provides a quick and easy way to access JSON data from WIL scripts. To facilitate access to the information contained in JSON data the JSON extender uses a simplified version of JSON paths. You use JSON paths to access a specific value or a group of values. They can also be used to obtain the JSON data type of a value.

A JSON path consists of a series of names wrapped in square brackets. Each name represents a JSON object or array except for the last name which can be the name for any value in the JSON container.  JSON objects hold key/value pairs. Each key is represented as a string in JSON and each value can be of any JSON data type. JSON array represents ordered list of values of any JSON data type.

Important: JSON objects and arrays are collectively referred to as containers in the extender's documentation.

Internally the extender stores references to JSON objects and arrays as container handles once the data is parsed but objects and arrays can also be accessed using the name associated with the object or array in the JSON data. Most extender functions do require a container handle in the first parameter. This handle is often the handle representing the entire JSON data but any extender container handle can be used as long as it is still present in the extender's handle table. The extender's JSON handles are returned by the jsParse, jsConNew, jsValueGet functions, or by accessing a WIL map element returned by the jsConMap function.

Accessing the value of the color name  in the JSON text

 { "color": "red", "rgba": [255,0,0,1] }

is as simple as using the name "color" in any extender function that accepts a JSON path parameter.

jsHndl1 = jsParse('{ "color": "red", "rgba": [255,0,0,1]}')

value = jsValueGet(jsHndl, "color")  ; The value variable will contain the string "red" after the call.

In instances of slightly more complex JSON data, you need to use multiple key names in the JSON path.

jsHndl2 = jsParse('{"name": "Jason Ray","profession": "Software Engineer","age": 41,"address": {"city": "Seattle","postalCode": 98109,"Country": "USA"}}')

value = jsValueGet(jsHndl2, "address.city")  ; The value variable contains the string "Seattle".

Notice the JSON path "address.city" used to obtain the city name. Address is the name of the nested JSON object and city is the name of the targeted value. Also notice that the two names are separated by a period(.). The period is the extender's default JSON name delimiter.

Each key name can be surrounded by square brackets ([key-name]). Use brackets when you need to avoid conflicts between JSON names and  name delimiters. While not necessary in this example, the path with brackets  becomes

"[address].[city]"

Important: brackets are required around key names that contain the current key name delimiter or one or more brackets.

Unlike JSON objects, JSON array values are accessed using a numeric index instead of a name string. This means the path to a value stored in a JSON array is slightly different.

The first example above contains a JSON array with the name "rgba". You can access one of the array's value by including the targeted values index number in square brackets next to the array's name. Unlike object names, JSON array's numeric indices square brackets are not optional. They are required.

value = jsValueGet(jsHndl1, "[rgba][0]")  ; The value variable will contain the number "255" after the call.

Notice that the array name and the array value's index are not separated by the period delimiter and that bracketed index is not included within the array name brackets.

JSON arrays present another instance where brackets are required. This happens when JSON data contains or is an array without a key name. A JSON array does not have a name when the entire JSON data is one or more array elements or when an array is an element of another array. The extender documentation calls these arrays anonymous arrays. Anonymous array values are accessed using a set of empty square brackets as the array name followed by the index in square brackets.

To access the value "Eric" in the JSON text

[[ 1, 9, 8, 4 ],["Eric", "Arthur", "Blair"]]

use a path with two sets of empty brackets.

jsHndl3 = jsParse('[[ 1, 9, 8, 4 ],["Eric", "Arthur", "Blair"]]')

value = jsValueGet(jsHndl3, "[][1].[][0]")  ; The value variable will contain the text "Eric" after the call.

In the JSON text above, the outermost JSON container is an array and the elements of that array are also arrays. The extender documentation refers to arrays that are am elements of another arrays as nested arrays.

The jsKeyPaths function creates JSON paths with brackets for you.