7.2 JSON

JSON (JavaScript Object Notation) is a lightweight data exchange language which is based on text description. Its advantages include being self-descriptive, easy to understand, etc. Even though it is a subset of JavaScript, JSON uses a different text format, the result being that it can be considered as an independent language. JSON bears similarity to C-family languages.

The biggest difference between JSON and XML is that XML is a complete markup language, whereas JSON is not. JSON is smaller and faster than XML, therefore it's much easier and quicker to parse in browsers, which is one of the reasons why many open platforms choose to use JSON as their data exchange interface language.

Since JSON is becoming more and more important in web development, let's take a look at the level of support Go has for JSON. You'll find that Go's standard library has very good support for encoding and decoding JSON.

Here we use JSON to represent the example in the previous section:

{"servers":[{"serverName":"Shanghai_VPN","serverIP":"127.0.0.1"},{"serverName":"Beijing_VPN","serverIP":"127.0.0.2"}]}

The rest of this section will use this JSON data to introduce JSON concepts in Go.

Parse JSON

Parse to struct

Suppose we have the JSON in the above example. How can we parse this data and map it to a struct in Go? Go provides the following function for just this purpose:

func Unmarshal(data []byte, v interface{}) error

We can use this function like so:

package main

import (
    "encoding/json"
    "fmt"
)

type Server struct {
    ServerName string
    ServerIP   string
}

type Serverslice struct {
    Servers []Server
}

func main() {
    var s Serverslice
    str := `{"servers":[{"serverName":"Shanghai_VPN","serverIP":"127.0.0.1"},{"serverName":"Beijing_VPN","serverIP":"127.0.0.2"}]}`
    json.Unmarshal([]byte(str), &s)
    fmt.Println(s)
}

In the above example, we defined a corresponding structs in Go for our JSON, using slice for an array of JSON objects and field name as our JSON keys. But how does Go know which JSON object corresponds to which specific struct filed? Suppose we have a key called Foo in JSON. How do we find its corresponding field?

• First, Go tries to find the (capitalised) exported field whose tag contains Foo.
• If no match can be found, look for the field whose name is Foo.
• If there are still not matches look for something like FOO or FoO, ignoring case sensitivity.

You may have noticed that all fields that are going to be assigned should be exported, and Go only assigns fields that can be found, ignoring all others. This can be useful if you need to deal with large chunks of JSON data but you only a specific subset of it; the data you don't need can easily be discarded.

Parse to interface

When we know what kind of JSON to expect in advance, we can parse it to a specific struct. But what if we don't know?

We know that an interface{} can be anything in Go, so it is the best container to save our JSON of unknown format. The JSON package uses map[string]interface{} and []interface{} to save all kinds of JSON objects and arrays. Here is a list of JSON mapping relations:

• bool represents JSON booleans,
• float64 represents JSON numbers,
• string represents JSON strings,
• nil represents JSON null.

Suppose we have the following JSON data:

b := []byte(`{"Name":"Wednesday","Age":6,"Parents":["Gomez","Morticia"]}`)

Now we parse this JSON to an interface{}:

var f interface{}
err := json.Unmarshal(b, &f)

The f stores a map, where keys are strings and values are interface{}'s'.

f = map[string]interface{}{
    "Name": "Wednesday",
    "Age":  6,
    "Parents": []interface{}{
        "Gomez",
        "Morticia",
    },
}

So, how do we access this data? Type assertion.

m := f.(map[string]interface{})

After asserted, you can use the following code to access data:

for k, v := range m {
    switch vv := v.(type) {
    case string:
        fmt.Println(k, "is string", vv)
    case int:
        fmt.Println(k, "is int", vv)
    case float64:
        fmt.Println(k,"is float64",vv)
    case []interface{}:
        fmt.Println(k, "is an array:")
        for i, u := range vv {
            fmt.Println(i, u)
        }
    default:
        fmt.Println(k, "is of a type I don't know how to handle")
    }
}

As you can see, we can parse JSON of an unknown format through interface{} and type assert now.

The above example is the official solution, but type asserting is not always convenient. So, I recommend an open source project called simplejson, created and maintained by by bitly. Here is an example of how to use this project to deal with JSON of an unknown format:

js, err := NewJson([]byte(`{
    "test": {
        "array": [1, "2", 3],
        "int": 10,
        "float": 5.150,
        "bignum": 9223372036854775807,
        "string": "simplejson",
        "bool": true
    }
}`))

arr, _ := js.Get("test").Get("array").Array()
i, _ := js.Get("test").Get("int").Int()
ms := js.Get("test").Get("string").MustString()

It's not hard to see how convenient this is. Check out the repository to see more information: https://github.com/bitly/go-simplejson.

Producing JSON

In many situations, we need to produce JSON data and respond to clients. In Go, the JSON package has a function called Marshal to do just that:

func Marshal(v interface{}) ([]byte, error)

Suppose we need to produce a server information list. We have following sample:

package main

import (
    "encoding/json"
    "fmt"
)

type Server struct {
    ServerName string
    ServerIP   string
}

type Serverslice struct {
    Servers []Server
}

func main() {
    var s Serverslice
    s.Servers = append(s.Servers, Server{ServerName: "Shanghai_VPN", ServerIP: "127.0.0.1"})
    s.Servers = append(s.Servers, Server{ServerName: "Beijing_VPN", ServerIP: "127.0.0.2"})
    b, err := json.Marshal(s)
    if err != nil {
        fmt.Println("json err:", err)
    }
    fmt.Println(string(b))
}

Output:

{"Servers":[{"ServerName":"Shanghai_VPN","ServerIP":"127.0.0.1"},{"ServerName":"Beijing_VPN","ServerIP":"127.0.0.2"}]}

As you know, all field names are capitalized, but if you want your JSON key names to start with a lower case letter, you should use struct tags. Otherwise, Go will not produce data for internal fields.

type Server struct {
    ServerName string `json:"serverName"`
    ServerIP   string `json:"serverIP"`
}

type Serverslice struct {
    Servers []Server `json:"servers"`
}

After this modification, we can produce the same JSON data as before.

Here are some points you need to keep in mind when trying to produce JSON:

• Field tags containing "-" will not be outputted.
• If a tag contains a customized name, Go uses this instead of the field name, like serverName in the above example.
• If a tag contains omitempty, this field will not be outputted if it is its zero-value.
• If the field type is bool, string, int, int64, etc, and its tag contains ",string", Go converts this field to its corresponding JSON type.

Example:

type Server struct {
    // ID will not be outputed.
    ID int `json:"-"`

    // ServerName2 will be converted to JSON type.
    ServerName  string `json:"serverName"`
    ServerName2 string `json:"serverName2,string"`

    // If ServerIP is empty, it will not be outputed.
    ServerIP   string `json:"serverIP,omitempty"`
}

s := Server {
    ID:         3,
    ServerName:  `Go "1.0" `,
    ServerName2: `Go "1.0" `,
    ServerIP:   ``,
}
b, _ := json.Marshal(s)
os.Stdout.Write(b)

Output:

{"serverName":"Go \"1.0\" ","serverName2":"\"Go \\\"1.0\\\" \""}

The Marshal function only returns data when it has succeeded, so here are some points we need to keep in mind:

• JSON only supports strings as keys, so if you want to encode a map, its type has to be map[string]T, where T is the type in Go.
• Types like channel, complex types and functions are not able to be encoded to JSON.
• Do not try to encode cyclic data, it leads to an infinite recursion.
• If the field is a pointer, Go outputs the data that it points to, or else outputs null if it points to nil.

In this section, we introduced how to decode and encode JSON data in Go. We also looked at one third-party project called simplejson which is for parsing JSON or unknown format. These are all useful concepts for developping web applications in Go.

Links

• Directory
• Previous section: XML
• Next section: Regexp