JSON

JSON stands for JavaScript Object Notation. It was designed to be a lightweight means of passing data between JavaScript systems. It uses a text-based format and is sufficiently general that it has become used as a general purpose serialisation method for many programming languages.

JSON serialises objects, arrays and basic values. The basic values include string, number, boolean values and the null value. Arrays are a comma-separated list of values that can represent arrays, vectors, lists or sequences of various programming languages. They are delimited by square brackets [ ... ]. Objects are represented by a list of “field: value” pairs enclosed in curly braces { ... }.

For example, the table of employees given earlier could be written as an array of employee objects:

  1. [
  2.    {Name: fred, Occupation: programmer},
  3.    {Name: liping, Occupation: analyst},
  4.    {Name: sureerat, Occupation: manager}
  5. ]

There is no special support for complex data types such as dates, no distinction between number types, no recursive types, etc. JSON is a very simple language, but nevertheless can be quite useful. Its text-based format makes it easy for people to use, even though it has the overheads of string handling.

From the Go JSON package specification, marshalling uses the following type-dependent default encodings:

  • Boolean values encode as JSON booleans.
  • Floating point and integer values encode as JSON numbers.
  • String values encode as JSON strings, with each invalid UTF-8 sequence replaced by the encoding of the Unicode replacement character U+FFFD.
  • Array and slice values encode as JSON arrays, except that []byte encodes as a base64-encoded string.
  • Struct values encode as JSON objects. Each struct field becomes a member of the object. By default the object’s key name is the struct field name converted to lower case. If the struct field has a tag, that tag will be used as the name instead.
  • Map values encode as JSON objects. The map’s key type must be string; the object keys are used directly as map keys.
  • Pointer values encode as the value pointed to. (Note: this allows trees, but not graphs!). A nil pointer encodes as the null JSON object.
  • Interface values encode as the value contained in the interface. A nil interface value encodes as the null JSON object.
  • Channel, complex, and function values cannot be encoded in JSON. Attempting to encode such a value cause Marshal to return an InvalidTypeError.
  • JSON cannot represent cyclic data structures and Marshal does not handle them. Passing cyclic structures to Marshal will result in an infinite recursion.

A program to store JSON serialised data into a file is

  1. /* SaveJSON
  2.  */
  4. package main
  6. import (
  7.     "encoding/json"
  8.     "fmt"
  9.     "os"
  10. )
  12. type Person struct {
  13.     Name  Name
  14.     Email []Email
  15. }
  17. type Name struct {
  18.     Family   string
  19.     Personal string
  20. }
  22. type Email struct {
  23.     Kind    string
  24.     Address string
  25. }
  27. func main() {
  28.     person := Person{
  29.         Name: Name{Family: "Newmarch", Personal: "Jan"},
  30.         Email: []Email{Email{Kind: "home", Address: "jan@newmarch.name"},
  31.             Email{Kind: "work", Address: "j.newmarch@boxhill.edu.au"}}}
  33.     saveJSON("person.json", person)
  34. }
  36. func saveJSON(fileName string, key interface{}) {
  37.     outFile, err := os.Create(fileName)
  38.     checkError(err)
  39.     encoder := json.NewEncoder(outFile)
  40.     err = encoder.Encode(key)
  41.     checkError(err)
  42.     outFile.Close()
  43. }
  45. func checkError(err error) {
  46.     if err != nil {
  47.         fmt.Println("Fatal error ", err.Error())
  48.         os.Exit(1)
  49.     }
  50. }

and to load it back into memory is

  1. /* LoadJSON
  2.  */
  4. package main
  6. import (
  7.     "encoding/json"
  8.     "fmt"
  9.     "os"
  10. )
  12. type Person struct {
  13.     Name  Name
  14.     Email []Email
  15. }
  17. type Name struct {
  18.     Family   string
  19.     Personal string
  20. }
  22. type Email struct {
  23.     Kind    string
  24.     Address string
  25. }
  27. func (p Person) String() string {
  28.     s := p.Name.Personal + " " + p.Name.Family
  29.     for _, v := range p.Email {
  30.         s += "\n" + v.Kind + ": " + v.Address
  31.     }
  32.     return s
  33. }
  34. func main() {
  35.     var person Person
  36.     loadJSON("person.json", &person)
  38.     fmt.Println("Person", person.String())
  39. }
  41. func loadJSON(fileName string, key interface{}) {
  42.     inFile, err := os.Open(fileName)
  43.     checkError(err)
  44.     decoder := json.NewDecoder(inFile)
  45.     err = decoder.Decode(key)
  46.     checkError(err)
  47.     inFile.Close()
  48. }
  50. func checkError(err error) {
  51.     if err != nil {
  52.         fmt.Println("Fatal error ", err.Error())
  53.         os.Exit(1)
  54.     }
  55. }

The serialised form is (formatted nicely)

  1. {"Name":{"Family":"Newmarch",
  2.          "Personal":"Jan"},
  3.  "Email":[{"Kind":"home","Address":"jan@newmarch.name"},
  4.           {"Kind":"work","Address":"j.newmarch@boxhill.edu.au"}
  5.          ]
  6. }

A client and server

A client to send a person’s data and read it back ten times is

  1. /* JSON EchoClient
  2.  */
  3. package main
  5. import (
  6.     "fmt"
  7.     "net"
  8.     "os"
  9.     "encoding/json"
  10.     "bytes"
  11.     "io"
  12. )
  14. type Person struct {
  15.     Name  Name
  16.     Email []Email
  17. }
  19. type Name struct {
  20.     Family   string
  21.     Personal string
  22. }
  24. type Email struct {
  25.     Kind    string
  26.     Address string
  27. }
  29. func (p Person) String() string {
  30.     s := p.Name.Personal + " " + p.Name.Family
  31.     for _, v := range p.Email {
  32.         s += "\n" + v.Kind + ": " + v.Address
  33.     }
  34.     return s
  35. }
  37. func main() {
  38.     person := Person{
  39.         Name: Name{Family: "Newmarch", Personal: "Jan"},
  40.         Email: []Email{Email{Kind: "home", Address: "jan@newmarch.name"},
  41.             Email{Kind: "work", Address: "j.newmarch@boxhill.edu.au"}}}
  43.     if len(os.Args) != 2 {
  44.         fmt.Println("Usage: ", os.Args[0], "host:port")
  45.         os.Exit(1)
  46.     }
  47.     service := os.Args[1]
  49.     conn, err := net.Dial("tcp", service)
  50.     checkError(err)
  52.     encoder := json.NewEncoder(conn)
  53.     decoder := json.NewDecoder(conn)
  55.     for n := 0; n < 10; n++ {
  56.         encoder.Encode(person)
  57.         var newPerson Person
  58.         decoder.Decode(&newPerson)
  59.         fmt.Println(newPerson.String())
  60.     }
  62.     os.Exit(0)
  63. }
  65. func checkError(err error) {
  66.     if err != nil {
  67.         fmt.Println("Fatal error ", err.Error())
  68.         os.Exit(1)
  69.     }
  70. }

and the corresponding server is

  1. /* JSON EchoServer
  2.  */
  3. package main
  5. import (
  6.     "fmt"
  7.     "net"
  8.     "os"
  9.     "encoding/json"
  10. )
  12. type Person struct {
  13.     Name  Name
  14.     Email []Email
  15. }
  17. type Name struct {
  18.     Family   string
  19.     Personal string
  20. }
  22. type Email struct {
  23.     Kind    string
  24.     Address string
  25. }
  27. func (p Person) String() string {
  28.     s := p.Name.Personal + " " + p.Name.Family
  29.     for _, v := range p.Email {
  30.         s += "\n" + v.Kind + ": " + v.Address
  31.     }
  32.     return s
  33. }
  35. func main() {
  37.     service := "0.0.0.0:1200"
  38.     tcpAddr, err := net.ResolveTCPAddr("tcp", service)
  39.     checkError(err)
  41.     listener, err := net.ListenTCP("tcp", tcpAddr)
  42.     checkError(err)
  44.     for {
  45.         conn, err := listener.Accept()
  46.         if err != nil {
  47.             continue
  48.         }
  50.         encoder := json.NewEncoder(conn)
  51.         decoder := json.NewDecoder(conn)
  53.         for n := 0; n < 10; n++ {
  54.             var person Person
  55.             decoder.Decode(&person)
  56.             fmt.Println(person.String())
  57.             encoder.Encode(person)
  58.         }
  59.         conn.Close() // we're finished
  60.     }
  61. }
  63. func checkError(err error) {
  64.     if err != nil {
  65.         fmt.Println("Fatal error ", err.Error())
  66.         os.Exit(1)
  67.     }
  68. }