JSON Decoding Functions

Owned by Jenni Wallin
Last updated: Feb 22, 2024 by Don Stone
4 min read

The functions described in this section are used to decode JSON formatted strings.

The following functions for JSON Decoding described here are:

jsonDecode

This function decodes a JSON formatted string to a json.JsonObject UDR or a json.JsonArray UDR.

The field asMap in a  json.JsonObject UDR contains key-value pairs where the value is a string, another json.JsonObject UDR or a  json.JsonArray UDR.

The field asList in a json.JsonArray UDR contains a list of json.JsonObject and json.JsonArray UDRs. 

any jsonDecode ( string jsonString)
ParameterDescription

jsonString

The JSON formatted string to decode

Returns

A json.JsonObject UDR or a json.JsonArray UDR

Note

jsonDecode can only decode valid JSON.

If the input is split due to size, the JSON may be invalid. The workaround for this is to use the baAppend function as shown in the example below.

Example - Example - Decoding JSON formatted string to json.JsonObject and json.JsonArray

import ultra.json;

bytearray ba;

consume {
    ba = baAppend(ba, input);
}

drain {
	if (ba != null) {
    	string s = baToStr(ba);
    	any js = jsonDecode(s);

    	if (isJsonObject(js)) {
    	    debugJsonObject((JsonObject) js, "");
    	} else if (isJsonArray(js)) {
    	    debugJsonArray((JsonArray) js, ""); 
    	}
	}
}

void debugJsonObject(JsonObject js, string parent) {
    map<string, any> mapObj = js.asMap;
    list<string> ikeys = mapKeys(mapObj);
    string path;

    if (strLength(parent) > 0) {
        path = path + "/" + parent; 
    }

    for (string i : ikeys) {  
        any value = mapGet(mapObj, i);

        if (isJsonObject(value)) {
            debugJsonObject((JsonObject) value, i);
        } else if (isJsonArray(value)) {
            debugJsonArray((JsonArray) value, i);   
        } else {  
            debug(path + "/" + i + ":" + value);
        }
    }
}

void debugJsonArray(JsonArray ja, string parent) {
    list<any> array = ja.asList;

    for (any i : array) {  
        if (isJsonObject(i)) {
            debugJsonObject((JsonObject) i, parent);
        } else if (isJsonArray(i)) {
            debugJsonArray((JsonArray) i, parent);        
        } 
    }
}

boolean isJsonObject(any value) {
    return instanceOf(value, JsonObject);
}

boolean isJsonArray(any value) { 
    return instanceOf(value, JsonArray);
}

jsonDecodeUdr

This function decodes a JSON formatted string to a DRUDR.

void jsonDecodeUdr ( string jsonString,
                     DRUDR udr,                                    
                     boolean requireExactMapping (optional) )
ParameterDescription

jsonString

The JSON string to decode

udrThe UDR to store the decoded data
requireExactMapping

Set to true if there must be matching UDR fields for all fields in the JSON string. The default value is false.

When requireExactMapping is set to true and the function fails to match a field, it will throw an exception. If the function is used in batch workflow, the exception will cause it to abort. In a real-time workflow, the function does not decode the string, but the workflow does not abort.

When requireExactMapping is set to false, the function will decode all JSON fields that can be mapped to a UDR field, the rest of the string will be ignored.

Returns

Nothing

Example - Encoding UDR to JSON and decoding the result

 Ultra:

internal itemUDR {
    int itId;
    string itDescription;      
    string itMisc1 : optional;
    list<string> itMisc2 : optional;   
};

internal transactionUDR {
    int trId ;
    string trDescription;
    float amount;
    long trDate;
    map<string, itemUDR> trItems;
    boolean trProcessed;
    ipaddress trSourceIP;  
    
};


APL:

import ultra.JSON_EXAMPLE.ULTRA_JSON_EXAMPLE;

consume {  
    //Item 1
    itemUDR item1 = udrCreate(itemUDR);
    item1.itId = 1;
    item1.itDescription = "Item1";  
    item1.itMisc2 = listCreate(string);
    listAdd(item1.itMisc2, "abc");
    listAdd(item1.itMisc2, "def");
    listAdd(item1.itMisc2, "ghi"); 
     
    //Item2
    itemUDR item2 = udrCreate(itemUDR);
    item2.itId = 1;
    item2.itDescription = "Item2";
    item2.itMisc1 = "abc";       
      
    //Transaction1        
    transactionUDR transaction1  = udrCreate(transactionUDR);
    transaction1.trId = 1;
    transaction1.trDescription = "Transaction1";
    transaction1.amount = 999.99;
    transaction1.trDate = dateCreateNowMilliseconds();
    transaction1.trItems = mapCreate(string, itemUDR);
    mapSet(transaction1.trItems, "item1Key",item1);  
    mapSet(transaction1.trItems, "item2Key",item1);  
    transaction1.trProcessed = true; 
    transaction1.trSourceIP = ipLocalHost();
     
    //Encode with JSON
    string json;
    json = jsonEncodeUdr(transaction1);        
    bytearray ba;
    strToBA(ba, json); 
    debug("Encoded JSON (" + baSize(ba) + "bytes):\n" + json + "\n" ); 
        
    //Decode from JSON
    transactionUDR transactionIn = udrCreate(transactionUDR);        
    jsonDecodeUdr(json, transactionIn);       
    debug("Decoded JSON:\n" + transactionIn);