JSON is so useful that almost all modern programming languages provide built-in support for working with it, including Go.
Working with JSON in Go
You can break most of the work you do with JSON into two general categories: marshalling and unmarshalling. Wikipedia defines marshalling.
In computer science, marshalling is the process of converting a memory representation of an object into a data format suitable for storage or transmission. It is generally used when data must be transferred between different parts of a computer program or from one program to another.
In simple terms, marshalling is the process of converting data stored in a variable into a form that is easy to pass to another program. Unmarshaling is the reverse process: it involves taking data formatted for transport and converting it into a form that is easier for your program to use.
Using Go, you can marshall native data structures into JSON. And you can do the reverse action, unmarshaling the JSON data into Go variables.
Marshalling for JSON in Go
Go provides the encoding/json package to make it easier for you to work with JSON. There are many functions included in this package, but the one you will be using for marshalling is the marshal function. Marshal has the following function signature.
This means that Marshal accepts a parameter of any data type and returns two values: a chunk of bytes and an error. In other words, you call Marshall the Go value, and it converts it to JSON and returns the JSON equivalent. If it encounters an error during the conversion process, it will return the error and an empty fragment.
As mentioned earlier, you can marshal any type of Go data into JSON, although in real life you’ll typically marshall structures. Because of this, Go provides a facility called struct tags to let you give additional instructions to marshal to modify structures.
A struct tag is a string that you include in your struct declaration next to a field’s data type. Structure tags let you adjust the way Marshal treats the field to which the tag belongs. You can use a structure tag to rename a field in the JSON output, or even omit it entirely. Structure tags (which Marshal recognizes) begin with the substring “json:”.
As an example, let’s say you have a struct Car that represents some information about a car. Here’s the code for creating the car and marshalling it into JSON.
The Car Brand, Model, and Price fields need to start with an uppercase letter, otherwise Marshall won’t be able to convert them. This also results in the JSON output field starting with uppercase. But what if you want the name to start with lowercase in the JSON, or if you want to rename the field entirely? This is where struct tags come in.
As you can see, the part of the struct tag after “json:” becomes the field name in marshall’s output. There is one exception: if it is the string “-“, Marshal omits that field from the output. You can read more about marshals and struct tags in the Go documentation.
Unmarshalling from JSON in Go
The encoding/json package also provides an unmarshalling function, called unmarshall.
Unlike Marshal, Unmarshal does not return a value. Instead, it accepts JSON as a slice of bytes in the first argument and then stores the converted data in the object pointed to by its second argument. Unmarshal also works with structure tags, but here, the tags tell Unmarshal which JSON fields correspond to which structure fields.
This indicates that the dummy JSON data was successfully unmarshalled into the jsonOutput structure.
Go makes working with JSON easy
With the encoding/json package, working with JSON in Go is as simple as two function calls: marshall and unmarshal. Go lets you customize the process of marshaling/unmarshalling JSON with struct tags.
Converting data to JSON is a great way to share it with another program or process. The format is universal enough to be as portable as JSON.