# Objects

*OBJ/JSON | JSON Object

## Invocation

json_obj=NEW("*obj/json")

## Description

The "*obj/json" object allows working with JSON data more easily than an associative array and comes with functions for advanced operations.

This object behaves similarly to an associative array and can still be used with dot key separators (key1.key2) but also comes with functions to make working with the data easier. Some of these functions include append, set, get and remove, as well as loading from associative arrays or strings, loading an XML object, saving and loading files, and working with subarrays within the object.

Numeric keys denote a list. List values can be accessed using their index. Including a # (pound sign) as the first character of a numeric key suppresses the creation of a list, and the numeric key displays without the pound sign. If you would like to use a pound sign as the first character, use ##. For an example, see Examples - Using Lists.

Null, Boolean and Null Lists are automatically converted from strings.

The "*obj/json" object is automatically sorted when using 'JV'=2. See 'JV' system parameter.

The Load_xml method does not convert xml attribute tags.

#### Note:
Keys are case sensitive.

Examples:

> json_obj'append("key_name", "value")

> list'append("1", 123)

> list'print("1.1") ! >123

> json_obj'remove("key1.key2")

> print json_obj'size()

Use these links to access additional examples provided below:

> Example - Creating and Working with the JSON
> Example - Loading Data
> Example - Using Lists

(The JSON object *OBJ/JSON was added in PxPlus 2025.)

## Methods

The following methods are supported:

Method | Description
Append(key$, value) Append(key$, value$) | Appends a key with a numeric or string value to the JSON object if the given key does not exist.
Append_json(jsonObj) | Appends all the elements from the given JSON object.
Append_json_to(key$, jsonObj) | Appends the elements of the given JSON object to a key if the key does not exist.
Append_to(key$, key2$, value) Append_to(key$, key2$, value$) | Appends key2 with a numeric or string value to the given key of the JSON object if key.key2 does not exist.
Clear( ) | Removes all values from the JSON object.
Exists(key$ ) | Returns 1 if key exists, 0 if key does not exist. (The Exists method was added in PxPlus 2025 Update 1.)
Find(regex$) | Returns a JSON list of keys that match the given regex$ (where regex$ is a string of a regular expression). Returns an empty list if no keys are found.
Find(regex$, key$) | Returns a JSON list of keys that match the given regex$ within the given sub-key (where regex$ is a string of a regular expression). Returns an empty list if no keys are found.
Find_any(regex$ ) | Returns 1 if any matching keys are found (where regex$ is a string of a regular expression). Returns 0 if none are found.
Find_any(regex$, key$ ) | Returns 1 if any matching keys in the given sub-key are found (where regex$ is a string of a regular expression). Returns 0 if none are found.
Find_any_val(regex$, val ) Find_any_val(regex$, val$) | Returns 1 if any matching keys that equal the given value are found (where regex$ is a string of a regular expression). Returns 0 if none are found. (The Find_any_val method was added in PxPlus 2025 Update 1.)
Find_any_val(regex$, val, key$ ) Find_any_val(regex$, val$, key$) | Returns 1 if any matching keys in the given sub-key are found that equal the given value (where regex$ is a string of a regular expression). Returns 0 if none are found. (The Find_any_val method was added in PxPlus 2025 Update 1.)
Find_val(regex$, val ) Find_val(regex$, val$) | Returns a JSON list of keys matching the given regex (where regex$ is a string of a regular expression) that equal the given value. Returns Error #11 if no keys are found. (The Find_val method was added in PxPlus 2025 Update 1.)
Find_val(regex$, val, key$ ) Find_val(regex$, val$, key$) | Returns a JSON list of keys matching the given regex (where regex$ is a string of a regular expression) that equal the given value within the given sub-key. (The Find_val method was added in PxPlus 2025 Update 1.)
Force_set(key$, value ) Force_set(key$, value$) | Set value without key validation.
Force_set(key$, value, ignore_remove) Force_set(key$, value$, ignore_remove) | Set value without key validation. ignore_remove=1 will ignore removing old values.
Get_json(key$) | Returns a JSON object of the given key. Returns Error #11 if the object size is 0.
Get_json(key$, full_key_flag) | Returns a JSON object of the given key. Keys will use the full key name when full_key_flag=1. Returns Error #11 if the object size is 0.
Get_json(key$, full_key_flag, no_validation) | Returns a JSON object of the given key. Keys will use the full key name when full_key_flag=1. no_validation=1 will ignore key validation. Returns Error #11 if the object size is 0. (The no_validation flag was added in PxPlus 2025 Update 1.)
Get_key$(index) | Returns the key at an index in the object.
Get_keys( ) | Returns a JSON object of all keys in the object. (The Get_keys method was added in PxPlus 2025 Update 1.)
Get_num(key$) | Returns a numeric from the key.
Get_num(key$, no_validation) | Returns a numeric from the key. no_validation=1 will ignore key validation.
Get_str$(key$) | Returns a string from the key.
Get_str$(key$, no_validation) | Returns a string from the key. no_validation=1 will ignore key validation.
Is_list_index(key$) | Returns 1 if the given key is an index of a list; otherwise, returns 0.
Is_num(key$) | Returns 1 if the given value is numeric; otherwise, returns 0.
Is_str(key$) | Returns 1 if the given value is a string; otherwise, returns 0.
Print( ) | Prints the JSON string.
Print(key$) | Prints the JSON string at the given key.
Print_keys( ) | Prints all keys within the object. (The Print_keys method was added in PxPlus 2025 Update 1.)
Print(sort_flag) | Prints the sorted JSON string when sort_flag=1.
Print(key$, sort_flag) | Prints the sorted JSON string at the given key when sort_flag=1.
Remove(key$) | Removes the key from the JSON object.
Remove(key$, no_validation) | Removes the key from the JSON object. no_validation=1 will ignore key validation. Returns Error #11 if the object size is 0. (The no_validation flag was added in PxPlus 2025 Update 1.)
Set(key$, value) Set(key$, value$) | Sets the key with a numeric or string value.
Set_json(key$, jsonObj) | Sets the key to the elements in the given JSON object. Returns Error #11 if the given object size is 0. #### Warning! Self-referencing will result in an Error #91: Class/Object in use.
Set_json(key$, jsonObj, no_validation) | Sets the key to key:json. no_validation=1 will ignore key validation. Returns Error #11 if the given object size is 0. #### Warning! Self-referencing will result in an Error #91: Class/Object in use. (The no_validation flag was added in PxPlus 2025 Update 1.)
Size( ) | Returns the total number of elements in the JSON object.
String$( ) | Returns a string of the JSON data.
String$(key$) | Returns a string of the JSON data at the given key.
String$(sort_flag) | Returns a string of the sorted JSON object when sort_flag=1.
String$(key$, sort_flag) | Returns a string of the sorted JSON object from the given key when sort_flag=1.

Loading and Saving Methods

Method | Description
Load_array(array${all}) | Load JSON from an associative array.
Load_array(array${all}, num_flag) | Load JSON from an associative array as only strings if num_flag=0.
Load_json_file(path$) | Loads the JSON object from the data in the given JSON file. Must start with "{" or "[".
Load_string(jsonString$) | Load JSON from a string.
Load_xml(xml_object) | Loads the data of an XML object into the JSON object. Converts strings to numeric if possible. Does not support duplicate XML tags.
Load_xml(xml_object, num_flag) | Loads the data of an XML object into the JSON object as only strings if num_flag=0. Does not support duplicate XML tags.
Load_xml(xml_object, num_flag, dupe_flag) | Loads the XML object data into the JSON object as only strings if num_flag=0. If dupe_flag=1, then duplicates will also be handled by condensing duplicates into a single list. Returns Error #11 if the object size is 0. #### Note: Loading data with very large amounts of duplicates may become very slow. (Support to handle duplicates was added in PxPlus 2025 Update 1.)
Save_json_file(path$) | Saves the JSON object data to a file.

## Example - Creating and Working with the JSON Object

Create an order:

order=new("*obj/json")
order'append("ID",12345)
order'append("Name","Apple")
order'append("Amount",10)
order'append("Unit Price",1.85)

Create order information:

order_info=new("*obj/json")
order_info'append("Customer Name","John Doe")
order_info'append("Date","01/01/2025")
order_info'append_to("Location","Country","Canada")
order_info'append_to("Location","Province","Ontario")
order_info'append("Location.City","Toronto")
order_info'append("Location.Address","123 Ontario Street")
order_info'append_json_to("Order",order)
drop object order

Set order total and print the object:

total=order_info'get_num("Order.Amount")*order_info'get_num("Order.Unit Price")
order_info'set("Total",total)
order_info'print()

Get a JSON object of the location and update the information:

location_info=order_info'get_json("Location")
location_info'set("Address","321 Ontario Street")
location_info'print()

Update the location in order_info:

order_info'set_json ("Location",location_info)
drop object location_info
order_info'print()

Save JSON object to file:

order_info'save_json_file("path\to\file.json")

Remove location data from order:

order_info'remove("Location")
order_info'print()

Load JSON object from file:

order_info'load_json_file("path\to\file.json")
order_info'print()
drop object order_info

## Example - Loading Data

Create an associative array:

dim my_array$
my_array$["FirstName"]="Jane"
my_array$["LastName"]="Smith"
my_array$["StreetNum"]="456"
my_array$["Address"]="Ontario Street"

Load data from an array:

my_obj=new("*obj/json")
my_obj'load_array(my_array${all})
my_obj'print()

Load data from a string:

string$="{ var1: [ ], var2: ""someString"", var3: 1.3 }"
my_obj'load_string(string$)
my_obj'print()

Create an XML object:

xml=new("*obj/xml")
xml'set_xml("<emp><name>John Smith</name><addr>456 Ontario Street</addr><age>40</age></emp>")
print xml'get_xml$()

Load XML into JSON:

my_obj'load_xml(xml)
my_obj'print()

Load the XML object without numeric conversion:

my_obj'load_xml(xml, 0)
my_obj'print()

## Example - Using Lists

Invoke a new object:

json_list=new("*obj/json")

Append some values to a list:

json_list'append("1", 1)
json_list'append("2", 2)

Create a new list under another key:

json_list'append_to("3.Key", "1", "Value")
json_list'append_to("3.Key", "2", "Value_2")

Create a second list under a different key:

json_list'append_to("3.Key_2", "1", "Value_3")

Create a non-list numeric key:(This example was added in PxPlus 2025 Update 1.)

json_list'append("3.#1", "Not a list")
json_list'append("3.##2", "Pound in name")
json_list'print()
drop object json_list

## See Also

*OBJ/XML - XML Object
Associative Arrays (Hash Tables)
DIM Define Arrays and Strings
DIM( ) Generate String/Get Array Size
'JV' JSON Version