Chapter 1. Admin Guide

1.1. Overview

This module introduces a new type of variable that provides both
serialization and de-serialization from JSON format.

The variable provides ways to access objects and arrays to add,replace
or delete values from the script.

The correct approach is to consider a json object as a hashtable
( you can put (key;value) pairs, and you can delete and get
values by key) and a json array as an array ( you can append,
delete and replace values).

Since the JSON format can have objects inside other objects
you can have multiple nested hashtables or arrays and you can
access these using paths.

1.2. Dependencies

1.2.1. OpenSIPS Modules

This module does not depend on other modules.

1.2.2. External Libraries or Applications

libjson
The libjson library can be downloaded from:
http://oss.metaparadigm.com/json-c/

1.3. Exported Parameters

The module does not export any parameters.

1.4. Exported Variables

This module exports the $json(id) variable.

The json variable provides methods to access fields
in json objects and to access indexes in json arrays.

1.4.1. Variable lifetime

The json variables will be available to the
process that created them from the moment they were
initialized. They will not reset per message or per
transaction. If you want to use the on a per message
basis you should initialize them each time.

1.4.2. Accessing the $json(id) variable

The grammar that describes the id is:

id = name(identifier)*

identifier = key | index

key = /string | /$var

index = [integer] | [$var] | []

The "[]" index represents appending to the array.
It should only be used when trying to set a value and
not when trying to get one.

Negative indexes can be used to access an array starting
from the end. So "[-1]" signifies the last element.

IMPORTANT: The id strictly complies to this grammar.
You should be careful when using spaces because they will
NOT be ignored. This was done to allow keys that contain
spaces.

Variables can be used as indexes or keys. Variables
that will be used as indexes must contain integer values.
Variables that will be used as keys should contain
string values.

Trying to get a value from a non-existing path
(key or value) will return the NULL value and notice
messages will be placed in the log describing the value
of the json and the path used.

Trying to replace or insert a value in a
non-existing path will cause an error in setting the value
and notice messages will be printed in the log
describing the value of the json and the path used

Example 1.1. Accessing the $json variable

...
$json(obj1/key) = "value"; #replace or insert the (key,value)
#pair into the json object;
$json(matrix1[1][2]) = 1; #replace the element at index 2 in the element
#at index 1 in an array
xlog("$json(name/key1[0][-1]/key2)"); # a more complex example
...

1.4.3. Returned values from $json(id)

If the value specified by the id is an integer
it will be returned as an integer value.

If the value specified by the id is a string it will
be returned as a string.

If the value specified by the id is any other
type of json ( null, boolean, object, array )
the serialized version of the object will be returned
as a string value. Using this and the ":="
operator you can duplicate json objects and put them
in other json objects ( for string or integer you may
use the "=" operator).

If the id does not exist a NULL value will be returned.

1.4.4. Operators for the $json(id) variable

There are 2 operators available for this variable.

1.4.4.1. The "=" operator

This will cause the value to be taken
as is and be added to the json object
( e.g. string value or integer value ).

Setting a value to NULL will cause it to be
deleted.

Example 1.3. Appending integers to arrays

...
$json(array1[]) = 1;
...

Example 1.4. Deleting the last element in an array

...
$json(array1[-1]) = NULL;
...

Example 1.5. Adding a string value to a json object

...
$json(object1/some_key) = "some_value";
...

1.4.4.2. The ":=" operator

This will cause the value to be taken
and interpreted as a json object
( e.g. this operator should be used to parse
json inputs ).

1.5. Exported Functions

1.5.1.
json_link("$json(dest_id)", "$json(source_id)")

This function can be used to link json objects together.
This will work simillar to setting a value to an object,
the only difference is that the second object is not
copied, only a reference is created.

Changes to any of the objects will be visible in both of
them.

You can use this method either to create references
so each time you access the field you don't
have to go through the full path
(for speed efficiency and shorter code), or
if you have an object that must be added to many
other objects and you don't want to copy it each
time (space and speed efficiency).

You can think of this object exactly as a reference
in an object-oriented language. Modifying fields
referenced by the variable will cause modifications
in all the objects, BUT modifying the variable itsef
will not cause any changes to other objects.

WARNING: You should be carefull when using references.
If you accidentally create a circular reference and try
to get the value from the object you will crash OPENSIPS.

...
$json(b) := "[1]";
/* NEVER do this, it is meant only to show where problems might occur */
json_link("$json(b[0])","$json(b)"); # replace 1 with a reference to b
xlog("\nTest link :\n$json(stub)\n$json(b)\n\n");
/* this will cause OPENSIPS to crash because it will continuously try
to get b, then b[0], then b ... */
...