JSON

JSON carries nested objects and arrays in one string, and is the format web services expect. LSL builds JSON from lists, reads and changes values by path, and converts JSON back to lists. Part of the Data Transmission feature.

Concepts

llList2Json builds a JSON_OBJECT from a strided list of key-value pairs, or a JSON_ARRAY from any list
- Integers and floats become numbers; "true", "false" and "null" become bare words
- Strings that are already valid JSON are kept as-is, so nested objects and arrays are built inside out
- Other strings become JSON strings, trimmed of surrounding whitespace; a string holding a number stays a string
llJson2List returns the top level only: a strided key-value list for an object, the items for an array
- Nested objects and arrays come back as JSON strings, ready for another call
A path is a list of specifiers: a string selects an object key, an integer an array index
- Negative indices are not supported
llJsonGetValue reads the value at a path; llJsonValueType tells its type
llJsonSetValue returns new JSON with the value at a path set, creating missing keys
- JSON_APPEND as the last specifier appends to an array
- JSON_DELETE as the value removes it, without pruning empty parents
Errors return JSON_INVALID: badly formed input, a missing path or an out-of-bounds index

Functions and events

`string`	`llList2Json(string type, list values)`
`list`	`llJson2List(string src)`
`string`	`llJsonGetValue(string json, list specifiers)`
`string`	`llJsonSetValue(string json, list specifiers, string value)`
`string`	`llJsonValueType(string json, list specifiers)`

Scripting Details

`string`	`llList2Json(string type, list values)` Converts the list values into a JSON string of the specified type (either a JSON_ARRAY or a JSON_OBJECT). Returns JSON_INVALID if an error is encountered.
`list`	`llJson2List(string src)` Parses the JSON string src and returns a list representing its top-level elements.
`string`	`llJsonGetValue(string json, list specifiers)` Parses the JSON string json and returns the value found by traversing the specified path of specifiers as a string.
`string`	`llJsonSetValue(string json, list specifiers, string value)` Returns a new JSON string representing json with the target located at specifiers set to value. Supports JSON_APPEND to append elements. Writing JSON_DELETE deletes the target. Overwriting array bounds or setting non-array levels with array indices returns JSON_INVALID.
`string`	`llJsonValueType(string json, list specifiers)` Parses the JSON string json and returns the JSON type constant (JSON_*) representing the value found at specifiers.

Example

string json = llList2Json(JSON_OBJECT, [
    "name", "Door",
    "pos", llList2Json(JSON_ARRAY, [12, 40, 22])
]);
// {"name":"Door","pos":[12,40,22]}

string x = llJsonGetValue(json, ["pos", 0]);             // "12"
json = llJsonSetValue(json, ["locked"], JSON_TRUE);      // adds "locked":true
json = llJsonSetValue(json, ["pos", JSON_APPEND], "1");  // appends to the array

Type constants

llJsonValueType returns one of these; some are also accepted as values. Each is a single reserved Unicode character, so it cannot collide with real text.

Constant	Meaning
`JSON_INVALID`	Input not well formed, or no value at the path
`JSON_OBJECT`	An object; also a type for `llList2Json`
`JSON_ARRAY`	An array; also a type for `llList2Json`
`JSON_NUMBER`	A number
`JSON_STRING`	A string
`JSON_NULL`	`null`; returned by `llJsonGetValue` for a null value
`JSON_TRUE`	`true`; as a value, `llJsonSetValue` writes the bare word
`JSON_FALSE`	`false`; as a value, `llJsonSetValue` writes the bare word
`JSON_APPEND`	Specifier for `llJsonSetValue` that appends to an array
`JSON_DELETE`	Value for `llJsonSetValue` that removes the key or element

See also Feature Data Transmission Category JSON SL Wiki Json usage in LSL Page CONTENT_TYPE_JSONPlanned Guide: sending nested data as JSON