# llJsonSetValue

*LSL function*

```lsl
string string llJsonSetValue(string json, list specifiers, string value);
```

- `string json`: Source JSON string to modify.
- `list specifiers`: A list of key names or array indices specifying the path to add, update, or delete.
- `string value`: New value to set, or the JSON_DELETE constant to delete the targeted element.

- Returns: `string`
- Energy: 10

Returns, if successful, a new [JSON](http://json.org) text *string* which is **json** with the value indicated by the **specifiers** list set to **value**.

If unsuccessful (usually because of specifying an out of bounds array index) it returns [JSON_INVALID](/constants/JSON_INVALID/).

An "out of bounds array index" is defined to be any Integer **specifiers** greater than the length of an existing array at that level within the Json text or greater than 0 (zero) at a level an array doesn't exist.

A special **specifiers**, [JSON_APPEND](/constants/JSON_APPEND/), is accepted which appends the **value** to the end of the array at the **specifiers** level. Care should be taken- if that level is not an array, the existing Value there will be overwritten and replaced with an array containing **value** at it's first (0) index.

Contrary to [list](https://wiki.secondlife.com/wiki/list)s and [string](https://wiki.secondlife.com/wiki/string)s, negative indexing of Json arrays is **not** supported.

If an existing "Key" is **specifiers** at that level, its Value will be overwritten by **value** unless **value** is the magic value [JSON_DELETE](/constants/JSON_DELETE/). If a value does not exist at **specifiers**, a new Key:Value pair will be formed within the Json object.

To delete an existing value at **specifiers**, use [JSON_DELETE](/constants/JSON_DELETE/) as the **value**. Note it will not prune empty objects or arrays at higher levels.

If **value** is [JSON_TRUE](/constants/JSON_TRUE/), [JSON_FALSE](/constants/JSON_FALSE/) or [JSON_NULL](/constants/JSON_NULL/), the Value set will be the bare words 'true', 'false' or 'null', respectively, at the **specifiers** location within **json**.

```lsl title="How to use" frame="terminal"
string result = llJsonSetValue("", [], "");
```

## Specification

See [Json usage in LSL](https://wiki.secondlife.com/wiki/Json_usage_in_LSL)

## Caveats

:::note
The below comment in regards to speed is unverified on modern simulator versions, and thus cannot be assumed to be true. **Always test execution speed claims for yourself.**
:::

- [llListReplaceList()](/functions/llListReplaceList/) is roughly 2.8x as fast in replacing a single value of a list than [llJsonSetValue()](/functions/llJsonSetValue/) is to replace a single value in a **json**.

:The length of the list/**json** are irrelevant here.

## Examples

<details open>
<summary>Example 1</summary>

```lsl collapse={1-15, 48-55, 100-106, 112-116, 122-140, 151-178}
string TEST_STRING_JSON;

init()
{
    TEST_STRING_JSON = "[9,\"<1,1,1>\",false,{\"A\":8,\"Z\":9}]";

//  [9,"<1,1,1>",false,{"A":8,"Z":9}]
    say("Original TEST_STRING_JSON: " + TEST_STRING_JSON);
}

run_json_test(string input)
{
    string output;

//  changing values within the json string

//  change the first value in the array to 10
    output = llJsonSetValue(input, [0], "10");

//  [10,"<1,1,1>",false,{"A":8,"Z":9}]
    say("( 1): " + output);

//  change the third value in the array to 'true'
    output = llJsonSetValue(input, [2], JSON_TRUE);

//  [9,"<1,1,1>",true,{"A":8,"Z":9}]
    say("( 2): " + output);

//  change the value of "A" within the Json object to 3
    output = llJsonSetValue(input, [3, "A"], "3");

//  [9,"<1,1,1>",false,{"A":3,"Z":9}]
    say("( 3): " + output);

//  adding a value or new key-value-pair within the input

//  add the value "Hello" to the end of the array
//      NOTE: One cannot insert, only add to the end
    output = llJsonSetValue(input, [JSON_APPEND], "Hello");

//  [9,"<1,1,1>",false,{"A":8,"Z":9},"Hello"]
    say("( 4): " + output);

//  add the key-value-pair "B":10 to the object
    output = llJsonSetValue(input, [3, "B"], "10");

//  [9,"<1,1,1>",false,{"A":8,"B":10,"Z":9}]
    say("( 5): " + output);

//  Things to look out for when modifying Json text
//      ~!~ Be careful when using this function ~!~

//  out of bounds array assignment:
//      defined as attempting to add a value to a position ...
//      ...greater than the length of the array (which may be 0)
//      JSON_APPEND is ALWAYS the preferred way to add to an array
    output = llJsonSetValue(input, [5], "10");

//  %EF%B7%90 (URL escaped JSON_INVALID)
    say("( 6): " + llEscapeURL(output));

//  BUT, this works, since it is in bounds
//      (eqivalent to JSON_APPEND in this case)
    output = llJsonSetValue(input, [4], "10");

//  [9,"<1,1,1>",false,{"A":8,"Z":9},10]
    say("( 7): " + output);

//  careless formation of new arrays
//      ( the 4 and all subsequent 0's are all in bounds.)
    output = llJsonSetValue(input, [4, 0, 0, 0], "10");

//  [9,"<1,1,1>",false,{"A":8,"Z":9},[[[10]]]]
    say("( 8): " + output);

//  overwriting an object with an array:
//      ~!~ mistaken use of JSON_APPEND on an object ~!~
    output = llJsonSetValue(input, [3, JSON_APPEND], "10");

//  [9,"<1,1,1>",false,[10]]
    say("( 9): " + output);

//  careless formation of new objects
//      NOTE: "Key" assignemts will NEVER result in a return of JSON_INVALID!
    output = llJsonSetValue(input, [3, "W", "X"], "10");

//  [9,"<1,1,1>",false,{"A":8,"W":{"X":10},"Z":9}]
    say("(10): " + output);

    output = llJsonSetValue(input, [3, "W", "X", "Y"], "10");

//  [9,"<1,1,1>",false,{"A":8,"W":{"X":{"Y":10}},"Z":9}]
    say("(11): " + output);

//  overwriting an array with an object
    output = llJsonSetValue(input, ["X"], "10");

//  {"X":10}
    say("(12): " + output);

//  special case considerations:

//  BUG-3692: (NOTE: Corrected in release 13.09.21.281328!)
//      a bug where, instead of JSON_INVALID being returned, if the out of
//      bounds index is at a lower level than the topmost (root) level, a
//      non-compliant JSON text would be formed
    output = llJsonSetValue(input, [1, 7], "Disappearing Text");

//  Note the "empty" second position that resulted in the returned array
//  [9,,false,{"A":8,"Z":9}]
// (But now correctly shows JSON_INVALID)
    say("(13): " + output);

//  though there is no way to directly delete a key-value-pair
//  nor remove a value from an array,
//  the use of JSON_NULL may prove adequate
    output = llJsonSetValue(input, [3, "A"], JSON_NULL);

//  [9,"<1,1,1>",false,{"A":null,"Z":9}]
    say("(14): " + output);

//  if a JSON text object has been formed with llList2Json()
//  that contains one or more duplicated "Keys", (allowable
//  but NOT recommended!) ANY change
//  made to that object will correct the condition,
//  with all but the last such "Key" being removed
    output = llList2Json(JSON_OBJECT, ["A", 1, "A", 2, "A", 3, "B", 4, "B", 4]);

//  both Keys "A" and "B" are duplicated
//  {"A":1,"A":2,"A":3,"B":4,"B":4}
    say("(15): " + output);

//  only the last value of the duplications is accessable though

//  3
    say("(16): " + llJsonGetValue(output, ["A"]));

//  condition corrected by adding a key-value-pair...

//  {"A":3,"B":4,"Z":5}
    say("(17): " + llJsonSetValue(output, ["Z"], "5"));

//  ... or by changing a value

// {"A":5,"B":4}
    say("(18): " + llJsonSetValue(output, ["A"], "5"));
}

say(string message)
{
    llOwnerSay(message);
//  llRegionSayTo(llGetOwner(), PUBLIC_CHANNEL, message);
//  llWhisper(PUBLIC_CHANNEL, message);
}

default
{
    on_rez(integer start_param)
    {
        llResetScript();
    }

    state_entry()
    {
        init();
    }

    touch_end(integer num_detected)
    {
//      copy 'TEST_STRING_JSON' from the following function call
//      to the string 'input' in the function declaration
//      and run a test on 'input' to not (!) modify 'TEST_STRING_JSON'
//      but its copy instead
        run_json_test(TEST_STRING_JSON);
    }
}
```

</details>

<details>
<summary>Double-quotes in string values are escaped. The following script inserts literal `string \"with\" quote` instead of `string "with" quotes` as the JSON value.</summary>

```lsl
default
{
    state_entry()
    {
        string test = "[\"a\"]";
        string add = "string \"with\" quotes";
        llOwnerSay(llJsonSetValue(test, [JSON_APPEND], add));
    }
}
```

</details>

## History

Date of Release [20/05/2013](https://wiki.secondlife.com/wiki/Release_Notes/Second_Life_Server/13#13-05-20-276191)

## Known issues

From the issue templates included by the wiki article:

- BUG-3692: type=bug|&lt;s>JSON_NULL may be deceptively returned instead of JSON_INVALID when \[http://tools.ietf.org/html/rfc4627 noncompliant Json text\] is encountered by either llJsonValueType or llJsonGetValue.&lt;/s> Fixed with release 13.09.21.281328.

## See also

### Functions

- [llList2Json](/functions/llList2Json/)
- [llJson2List](/functions/llJson2List/)
- [llJsonGetValue](/functions/llJsonGetValue/)
- [llJsonValueType](/functions/llJsonValueType/)

### Articles

- [Typecast](https://wiki.secondlife.com/wiki/Typecast)

---

*Source: [LlJsonSetValue](https://wiki.secondlife.com/wiki/LlJsonSetValue) on the Second Life Wiki. Content from the Second Life Wiki articles LlJsonSetValue (revision 1216020, 2023-12-30), Template:Issues/BUG-3692 (revision 1182085, 2013-10-02) and Template:LSL Function/negative index (revision 1200041, 2016-05-02), CC BY-SA 3.0.*

---

From lsl.dev: https://lsl.dev/functions/llJsonSetValue/