How to read and parse JSON with Zig 0.13

While I know this post may seem obvious to many, I believe it can be helpful to others since it took me some time to understand JSON parsing in Zig (version 0.13 specifically). My goal is to demonstrate the process clearly and, hopefully, save others time.

Read JSON file

Say you have a JSON file example.json that looks like the following:

{
    "string": "foobar",
    "number": 1,
    "boolean": true,
    "array": [1, 2, 3],
    "map": {
        "a": 0,
        "b": 1,
        "c": 2
    }
}

You would need to read the file into a buffer as follows:

const std = @import("std");

var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
defer arena.deinit();
const allocator = arena.allocator();

var file = try std.fs.cwd().openFile("example.json", .{});
defer file.close();

const stat = try file.stat();
const buffer = try allocator.alloc(u8, stat.size);
// defer allocator.free(buffer); -> not required as we're using an `ArenaAllocator`

_ = try file.reader().read(buffer);

Parse JSON with std.json

So that the content of the buffer is the JSON data as a string slice, to read and parse the JSON strings you should check first the std.json documentation.

The JSON string can be parsed with either the std.json.parseFromSlice function from the std lib (more information here), or if you are using an ArenaAllocator you can instead use std.json.parseFromSliceLeaky as the allocations there are not carefully tracked, and the arena deallocation will release everything i.e. no need for specific handling of the deallocation of every resource.

Parse with std.json.Value

var parsed = try std.json.parseFromSliceLeaky(
   std.json.Value,
   allocator,
   buffer,
   .{},
);
defer parsed.deinit();

As you can see above, the type for the parsed variable will be an std.json.Value, which is an "arbitrary" type holding the information read from the JSON string.

So below you can find how to access the different type of fields contained within the std.json.Value on the first-level, and then it can be easily extended to nested content or different types easily. The code below shows how to parse the values for each of the different keys defined above in the example.json file.

if (parsed.value.object.get("string")) |value| {
    if (value == .string) {
        std.debug.print("\nstring contains = {s}", .{ value.string });
    }
}

if (parsed.value.object.get("number")) |value| {
    if (value == .integer) {
        std.debug.print("\nnumber contains = {d}", .{ value.integer });
    }
}

if (parsed.value.object.get("boolean")) |value| {
    if (value == .bool) {
        std.debug.print("\nboolean contains = {b}", .{ value.bool });
    }
}

if (parsed.value.object.get("array")) |value| {
    if (value == .array) {
        for (value.array.items) |item| {
            if (item == .integer) {
                std.debug.print("\nitem contains = {d}", .{ item.integer });
            }
        }
    }
}

if (parsed.value.object.get("map")) |value| {
    if (value == .object) {
        for (vocab_json.object.keys(), vocab_json.object.values()) |k, v| {
            if (v == .integer) {
                std.debug.print("\nkey contains = {s}, and value contains = {d}", .{ k, v });
            }
        }
    }
}

Parse with custom struct

Alternatively, you could instead just use a custom struct instead of the default std.json.Value to parse the values from the JSON, in case you know those and their types in advance as it follows:

const Info = struct {
    string: []const u8,
    number: i64,
    boolean: bool,
    array: []i64,
    map: std.StringHashMap(i64),
};

const parsed = try std.json.parseFromSliceLeaky(
   Info,
   allocator,
   buffer,
   .{},
);
defer parsed.deinit();

std.debug.print("\nstring contains = {s}", .{ parsed.string });
std.debug.print("\nnumber contains = {d}", .{ parsed.number });
std.debug.print("\nboolean contains = {b}", .{ parsed.boolean });
std.debug.print("\narray contains = {any}", .{ parsed.array });
std.debug.print("\nmap contains = {any}", .{ parsed.map });

Some useful notes

• When using a custom struct to parse the JSON data, note that you can also define nested structs inside, leading to more complex schemas or JSON definitions, and the std.json will handle the proper parsing for those.

• When reading numeric values from the JSON file, it's recommended to use either i64 or f64 types unless explicitly defined otherwise, since the numeric values defined in the JSON could exceed other ranges as e.g. i32 or f32. If you know those types in advance, then you can use those to save some memory.

• Since the get method in the std.json.Value returns optional values, those can be unwrapped using orelse on the optional value as follows:

  const value = json.value.object.get("string") orelse return error.KeyNotFound;
  std.debug.print("\nstring contains = {s}", .{ value.string });

  Or with a forced unwrap i.e. .?, even though it's not recommended, as it follows:

  const value = json.value.object.get("string").?.string;
  std.debug.print("\nstring contains = {s}", .{ value });

• std.json.Value holds immutable objects i.e. given an ArrayHashMap you won't be able to create an iterator over its contents, because iterators require a mutable object, whilst std.json.Value holds immutable objects instead.

• To inspect the keys of the JSON you can run the following:

  const keys = parsed.value.object.keys();
  std.debug.print("\nfound keys: {s}", .{ keys });

Conclusion

That's pretty much it! Zig's explicit memory management and strict typing make JSON parsing a deliberate process. While can seem challenging, it encourages robust error handling and type safety.

Feel free to reach out in the social links in the footer below!