JSON and Go - The Go Programming Language

Common problems companies solve with Go
Stories about how and why companies use Go
How Go can help keep you secure by default
The official Go language specification
A complete introduction to building software with Go
Reference documentation for Go's standard library
Learn what's new in each Go release
Tips for writing clear, performant, and idiomatic Go code
Videos from prior events
Meet other local Go developers
Learn and network with Go developers from around the world
The Go project's official blog.
Get help and stay informed from Go
Andrew Gerrand 25 January 2011
[Note, August 2026: Go 1.27 introduces a new encoding/json/v2 package. For an updated introduction to working with JSON in Go, see “Tutorial: Working with JSON.”]
JSON (JavaScript Object Notation) is a simple data interchange format. Syntactically it resembles the objects and lists of JavaScript. It is most commonly used for communication between web back-ends and JavaScript programs running in the browser, but it is used in many other places, too. Its home page, json.org, provides a wonderfully clear and concise definition of the standard.
With the json package it’s a snap to read and write JSON data from your Go programs.
To encode JSON data we use the Marshal function.
Given the Go data structure, Message,
and an instance of Message
we can marshal a JSON-encoded version of m using json.Marshal:
If all is well, err will be nil and b will be a []byte containing this JSON data:
Only data structures that can be represented as valid JSON will be encoded:
JSON objects only support strings as keys; to encode a Go map type it must be of the form map[string]T (where T is any Go type supported by the json package).
Channel, complex, and function types cannot be encoded.
Cyclic data structures are not supported; they will cause Marshal to go into an infinite loop.
Pointers will be encoded as the values they point to (or ’null’ if the pointer is nil).
The json package only accesses the exported fields of struct types (those that begin with an uppercase letter). Therefore only the exported fields of a struct will be present in the JSON output.
To decode JSON data we use the Unmarshal function.
We must first create a place where the decoded data will be stored
and call json.Unmarshal, passing it a []byte of JSON data and a pointer to m
If b contains valid JSON that fits in m, after the call err will be nil and the data from b will have been stored in the struct m, as if by an assignment like:
How does Unmarshal identify the fields in which to store the decoded data? For a given JSON key "Foo", Unmarshal will look through the destination struct’s fields to find (in order of preference):
An exported field with a tag of "Foo" (see the Go spec for more on struct tags),
An exported field named "Foo", or
An exported field named "FOO" or "FoO" or some other case-insensitive match of "Foo".
What happens when the structure of the JSON data doesn’t exactly match the Go type?
Unmarshal will decode only the fields that it can find in the destination type. In this case, only the Name field of m will be populated, and the Food field will be ignored. This behavior is particularly useful when you wish to pick only a few specific fields out of a large JSON blob. It also means that any unexported fields in the destination struct will be unaffected by Unmarshal.
But what if you don’t know the structure of your JSON data beforehand?
The interface{} (empty interface) type describes an interface with zero methods. Every Go type implements at least zero methods and therefore satisfies the empty interface.