Golang JSON: Marshal, Unmarshal and Struct Tags

Marshal and Unmarshal

json.Marshal turns a Go value into JSON bytes. json.Unmarshal fills a Go value from JSON bytes. Struct tags choose the JSON field names.

package main

import (
	"encoding/json"
	"fmt"
)

type User struct {
	ID    int      `json:"id"`
	Name  string   `json:"name"`
	Email string   `json:"email,omitempty"`
	Tags  []string `json:"tags"`
}

func main() {
	u := User{ID: 1, Name: "Ada", Tags: []string{"admin"}}

	data, err := json.Marshal(u)
	if err != nil {
		fmt.Println("marshal:", err)
		return
	}
	fmt.Println(string(data))

	var back User
	input := []byte(`{"id": 2, "name": "Linus", "email": "l@example.com", "tags": ["kernel", "git"]}`)
	if err := json.Unmarshal(input, &back); err != nil {
		fmt.Println("unmarshal:", err)
		return
	}
	fmt.Printf("%+v\n", back)
}

Email is missing from the first output because of omitempty and an empty string. Unmarshal needs a pointer (&back); passing the value itself returns an InvalidUnmarshalError.

Struct tags

The tag syntax is json:"name,option,option".

package main

import (
	"encoding/json"
	"fmt"
	"time"
)

type Account struct {
	ID        int       `json:"id"`
	Password  string    `json:"-"`
	Nickname  string    `json:"nickname,omitempty"`
	Balance   int64     `json:"balance,string"`
	CreatedAt time.Time `json:"created_at,omitempty"` // omitempty never omits a struct
	DeletedAt time.Time `json:"deleted_at,omitzero"`  // Go 1.24: omitted when zero
	internal  string    // unexported: always ignored
}

func main() {
	a := Account{ID: 7, Password: "hunter2", Balance: 1500, internal: "x"}
	out, err := json.MarshalIndent(a, "", "  ")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(out))
}

The password never leaves the struct, the balance is quoted, and deleted_at disappears while created_at prints the zero time 0001-01-01T00:00:00Z. That difference is why omitzero was added: omitempty has never worked for structs, and it is a long-standing surprise with time.Time. On Go 1.23 and earlier, use a *time.Time with omitempty to get the same effect.

MarshalIndent(v, prefix, indent) produces readable output. Use it for config files and debugging; APIs usually send compact JSON.

Exported fields only

encoding/json uses reflection and can only see exported fields. This is the most common JSON bug in Go:

type point struct {
	x, y int // lowercase: json.Marshal(point{1, 2}) gives {}
}

No error, no warning, just {} on the way out and fields left at zero on the way in. Capitalize the fields and add tags for lowercase keys.

How decoding matches fields

When unmarshaling into a struct:

• Keys are matched to the tag name, or to the field name, case-insensitively. {"NAME": "x"} fills a field tagged json:"name".
• Keys with no matching field are ignored silently.
• Fields with no matching key keep their current value. Unmarshal does not reset them, so decoding into a struct that already has data merges into it.
• A type mismatch (a string where the struct has an int) returns an *json.UnmarshalTypeError, but the other fields are still filled.

To reject unexpected keys, for example in a strict API or a config file with typos, use a Decoder with DisallowUnknownFields:

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

type Config struct {
	Port  int  `json:"port"`
	Debug bool `json:"debug"`
}

func main() {
	input := `{"port": 8080, "debgu": true}` // typo in "debug"

	var lenient Config
	err := json.Unmarshal([]byte(input), &lenient)
	fmt.Printf("Unmarshal: %+v, err=%v\n", lenient, err)

	var strict Config
	dec := json.NewDecoder(strings.NewReader(input))
	dec.DisallowUnknownFields()
	err = dec.Decode(&strict)
	fmt.Println("Decoder:", err)

	var typed Config
	err = json.Unmarshal([]byte(`{"port": "8080"}`), &typed)
	fmt.Println("type mismatch:", err)
}

Unknown structure: map[string]any

When you do not know the shape in advance, decode into map[string]any or any. The mapping is fixed:

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

func main() {
	input := `{"name": "widget", "price": 9.5, "stock": 3, "tags": ["a", "b"], "meta": {"id": 9007199254740993}}`

	var m map[string]any
	if err := json.Unmarshal([]byte(input), &m); err != nil {
		fmt.Println(err)
		return
	}

	name, _ := m["name"].(string)
	stock, _ := m["stock"].(float64) // numbers are float64, even 3
	tags, _ := m["tags"].([]any)
	fmt.Println(name, int(stock), len(tags))

	meta := m["meta"].(map[string]any)
	fmt.Printf("id as float64: %.0f\n", meta["id"]) // precision lost

	// UseNumber keeps numbers as json.Number (a string) for exact handling.
	dec := json.NewDecoder(strings.NewReader(input))
	dec.UseNumber()
	var exact map[string]any
	if err := dec.Decode(&exact); err != nil {
		fmt.Println(err)
		return
	}
	id, err := exact["meta"].(map[string]any)["id"].(json.Number).Int64()
	fmt.Println("id with UseNumber:", id, err)
}

Two traps are visible in the output. Every number is float64, so m["stock"].(int) would fail. And integers above 2^53 lose precision as float64: the id 9007199254740993 comes back as ...992. UseNumber avoids both.

If you know part of the structure, decode that part into a struct and use json.RawMessage for the rest. It holds the raw bytes of a field so you can decode it later, once you know its type.

Slices, maps, pointers and nil

The nil versus empty slice difference matters for API clients that expect an array. Initialize with []T{} or make([]T, 0) when the field must be [].

Use a pointer field (*int, *bool) when you need to tell "absent" from "zero" on input. After unmarshaling, a nil pointer means the key was missing or null; a pointer to 0 means the client sent 0.

Streams: Encoder and Decoder

json.Marshal and Unmarshal work on whole byte slices. For an io.Reader or io.Writer (an HTTP body, a file, stdin), use json.NewDecoder and json.NewEncoder. A Decoder can also read a sequence of JSON values one at a time:

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"os"
	"strings"
)

type Event struct {
	Type string `json:"type"`
	N    int    `json:"n"`
}

func main() {
	// Newline-delimited JSON, as in log files and many streaming APIs.
	stream := `{"type":"click","n":1}
{"type":"view","n":2}
{"type":"click","n":3}`

	dec := json.NewDecoder(strings.NewReader(stream))
	clicks := 0
	for {
		var e Event
		err := dec.Decode(&e)
		if errors.Is(err, io.EOF) {
			break
		}
		if err != nil {
			fmt.Println("decode:", err)
			return
		}
		if e.Type == "click" {
			clicks++
		}
	}
	fmt.Println("clicks:", clicks)

	enc := json.NewEncoder(os.Stdout)
	enc.SetEscapeHTML(false) // keep <, > and & readable
	enc.SetIndent("", "  ")
	if err := enc.Encode(map[string]any{"clicks": clicks, "note": "a < b & c"}); err != nil {
		fmt.Println("encode:", err)
	}
}

Encoder.Encode writes a trailing newline after each value. By default both Marshal and Encoder escape <, > and & as \u003c, \u003e and \u0026, so the JSON is safe to embed in HTML. SetEscapeHTML(false) turns that off. In HTTP handlers, json.NewDecoder(r.Body).Decode(&v) and json.NewEncoder(w).Encode(v) are the usual pair.

Custom encoding

A type can control its own JSON by implementing json.Marshaler and json.Unmarshaler. A common case is an iota enum that should appear as a name, not a number:

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

type Level int

const (
	Low Level = iota
	High
)

var levelNames = []string{"low", "high"}

func (l Level) MarshalJSON() ([]byte, error) {
	return json.Marshal(levelNames[l])
}

func (l *Level) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}
	for i, name := range levelNames {
		if strings.EqualFold(s, name) {
			*l = Level(i)
			return nil
		}
	}
	return fmt.Errorf("unknown level %q", s)
}

type Alert struct {
	Msg   string `json:"msg"`
	Level Level  `json:"level"`
}

func main() {
	out, _ := json.Marshal(Alert{Msg: "disk full", Level: High})
	fmt.Println(string(out))

	var a Alert
	err := json.Unmarshal([]byte(`{"msg":"cpu","level":"LOW"}`), &a)
	fmt.Printf("%+v %v\n", a, err)

	err = json.Unmarshal([]byte(`{"msg":"cpu","level":"urgent"}`), &a)
	fmt.Println(err)
}

MarshalJSON has a value receiver so it works for both values and pointers; UnmarshalJSON needs a pointer receiver because it modifies the value. Types that only need a string form can implement encoding.TextMarshaler (MarshalText) instead, which also makes them usable as map keys.

Common mistakes

• Lowercase field names. They are silently skipped.
• Passing a value to Unmarshal. It needs a pointer.
• Ignoring the error. Malformed JSON and type mismatches are reported only through it.
• Assuming numbers in map[string]any are int. They are float64.
• Expecting omitempty to drop an empty struct or a zero time.Time. Use omitzero on Go 1.24, or a pointer.
• Relying on field order in maps. Map keys are sorted on output; struct fields keep their declaration order.