Skip to content

Build JSON

Info

This how-to assumes you are familiar with setting up a project either manually or via VoltScript Dependency Management. If you are not, follow the Intro to VoltScript Tutorials.

Introduction

JSON can be constructed manually as a string. But this is an onerous and accident-prone way of generating output. JsonVSE was designed to improve the developer experience for both reading and writing JSON. In this tutorial, we will focus on writing JSON.

VoltScript dependencies

Incorporating JsonVSE is straightforward. You just need to add the following JSON object to the vsesDependencies element in your atlas.json.

        "JsonVSE": {
            "library": "25265",
            "version": "1.0.1",
            "module": "25877/20841",
            "repository":"volt-mx-marketplace"
        }

You'll need to add to your repositories object in the atlas.json of your project:

        {
            "id": "volt-mx-marketplace",
            "type": "marketplace",
            "url": "https://community.demo-hclvoltmx.com/marketplace/asset"
        }

To use the extension in your script, enter UseVSE "*JsonVSE".

JsonObject class

Construct JSON objects and arrays

The JsonObject class is used for both JSON objects and JSON arrays. There is no difference to how you instantiate the object. The difference comes in how you populate them.

Function buildJsonObj() as JsonObject
    Dim jsonObj as New JsonObject

    Call jsonObj.insertValue("String", "One")
    Call jsonObj.insertValue("Number", 2)

    Return jsonObj
End Function

The method insertValue() is used to build a JSON object. The first parameter is the label, the second parameter is the value.

Function buildJsonArr() as JsonObject
    Dim jsonArr as New JsonObject

    Call jsonArr.appendToJsonArray("One")
    Call jsonArr.appendToJsonArray("Two")
    Call jsonArr.appendToJsonArray(2)

    Return jsonArr
End Function

The method appendToJsonArray() is used to build a JSON array. Because the JSON array only contains values, there is only one parameter to pass. Because a JSON array can contain mixed value types, subsequent calls to appendToJsonArray() don't need to pass the same parameter type.

Add arrays to existing JsonObject

An array can be passed into a JsonObject in two ways. The first is by constructing a VoltScript array and calling the insertValue() method.

Sub addVSArrToObj(jsonObj as JsonObject)
    Dim vals(1) as String
    vals(0) = "Hello"
    vals(1) = "World"

    Call jsonObj.insertValue("StringArray", vals)
End Function

Alternatively, a JsonObject that's an array can be loaded, calling either insertValue() or insertObject() methods. If using insertValue(), you need to pass the label as a parameter. The label property of the JsonObject will be ignored. If using insertObject(), the label property of the JsonObject can be leveraged or the label explicitly passed as a parameter.

Sub addJsonArrToObject(jsonObj as JsonObject, jsonArr as JsonObject)
    Call jsonObj.insertValue("JSONArray", jsonArr)

    Call jsonObj.insertObject(jsonArr, "ObjectArray") ' (1)
    jsonArr.label = "ArrayLabel"
    Call jsonObj.insertObject(jsonArr) ' (2)
End Function
  1. "ObjectArray" label is used, regardless of the label of the jsonArr object.
  2. jsonArr.label is used as the label.

Add JsonObjects to a JsonObject

A JsonObject can be loaded calling either insertValue() or insertObject() methods. If using insertValue(), you need to pass the label as a parameter. The label property of the JsonObject will be ignored. If using insertObject(), the label property of the JsonObject can be leveraged or the label explicitly passed as a parameter.

Sub addJsonObj(jsonObj as JsonObject)
    Dim childObj as New JsonObject
    Call childObj.insertValue("hello","world")

    Call jsonObj.insertValue("child1", childObj)
    Call jsonObj.insertObject(childObj, "child2")

    childObj.label = "child3"
    Call jsonObj.insertObject(childObj)
End Function

"By Value" Addition

JsonObjects and JsonArrays loaded by insertValue() or insertObject() are passed by value, not by reference. This means the contents are deep-copied into the new parent. As a result, subsequent changes to the child won't be reflected in the parent.

Function modifyChild() as JsonObject
    Dim parent as JsonObject
    Dim childObj as JsonObject
    Call childObj.insertValue("elem1","hello world")
    childObj.label = "child"

    Call parent.insertObject(childObj)
    Call childObj.insertValue("elem2",2)
    Print parent.toString(false) ' (1)
    Return parent
End Function
  1. This code will print {"child":{"elem1":"hello world"}} because "elem2" was added to the child JsonObject after it was copied into the parent.

Return JSON

We use toString(false) to return a string of compact JSON.

Print parent.toString(false)

This will print {"child":{"elem1":"hello world"}}.

Use toString(true) to return a string of JSON pretty-printed.

Print parent.toString(true)

This will print:

{
    "child": {
        "elem1": "hello world"
    }
}

The complete implementations of the code snippets are available on GitHub.