Suppose we're consuming a web API that returns an array of person objects with a name and ID field. We get the following JSON string from the API:

[{"name":"Alice","id":1},{"name":"Bob","id":2}]

Let's execute the following steps to use the std.json module:

The code is as follows:

void main() {
    import std.json, std.algorithm, std.stdio;
    auto list = parseJSON(`[{"name":"Alice","id":1},{"name":"Bob","id":2}]);
    foreach(person; list.array.map!(a => a.object)) {
         writeln("ID #", person["id"].integer, " is ", person["name"].str);
    }
    JSONValue newPerson;
    JSONValue[string] obj;
    obj["name"].str = "Charlie";
    obj["id"].integer = 3;
    newPerson.object = obj;
    list.array = list.array ~ newPerson;; // append it to the list
    writeln(toJSON(&list)); // print out the new json
}

It will print the following output:

[{"name":"Alice","id":1},{"name":"Bob","id":2},{"name":"Charlie","id":3}]

Phobos' std.json module provides a tagged union to represent a dynamic JSONValue. To use it, you can explicitly check the type with the type property, or simply access the type you need through its str, object, array, integer, and other properties. It will throw an exception if you try to access a property of the wrong type. You can query the current type with the type property.

Array elements in std.json are also JSONValues, which means they need to be accessed through the type properties. That is why we called map on the array. We can't work directly with JSONValue, so mapping it to an object gives something we can immediately use. The map function is a function from std.algorithm that calls the given predicate on each element in the array.

JSONValue properties are either read or write. We cannot modify them in-place. Instead, we read the data or create a temporary file to do our edits then set the finished data back to it.

Finally, toJSON takes a pointer to a root element and returns the JSON string it represents.