Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Encoding and Data Formats

Go json.Unmarshal() function

Reference for Go json.Unmarshal: decode JSON bytes into structs, maps and slices, how fields are matched, any and float64 pitfalls, and the errors it returns.

json.Unmarshal parses JSON text and stores the result in the value its second argument points to. That value can be a struct, a map, a slice, a basic type, or any when you don't know the shape in advance.

The whole input is validated before anything is stored, so syntax errors never leave you with a half-filled result. Type mismatches (a string where a number was expected) are different: Unmarshal keeps going, fills what it can, and reports the first such error at the end.

Go
var p Person
err := json.Unmarshal(data, &p)

Try it

Go Into a struct

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Dynamic JSON and errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
func Unmarshal(data []byte, v any) error
Parameter Description
data One complete JSON value. Surrounding whitespace is fine; extra text after the value is an error.
v A non-nil pointer to the destination.

Decoding rules. JSON null sets a pointer, interface, map or slice to nil and leaves other types unchanged. Into any, objects become map[string]any, arrays []any, numbers float64, strings string, booleans bool. A JSON number that doesn't fit an integer field is an error. Unmarshal into a slice replaces its contents; into a map it adds to the existing map; into an array it fills in order and zeroes the rest.

Errors. *json.SyntaxError (malformed input, with Offset), *json.UnmarshalTypeError (wrong type; Field, Value, Type), *json.InvalidUnmarshalError (nil or non-pointer destination), or any error returned by a custom UnmarshalJSON.

Usage notes

  • Pointer required. json.Unmarshal(data, p) with a struct value (not &p) fails with "Unmarshal(non-pointer ...)".
  • Matching is forgiving: keys match field names or tags case-insensitively, and unknown keys are skipped. To reject unknown keys, use a Decoder and DisallowUnknownFields().
  • Large integers: when decoding into any, IDs above 2^53 lose precision as float64. Use typed fields, json.Number (via Decoder.UseNumber), or a string tag option.
  • Missing vs. zero: a field absent from the JSON is indistinguishable from a zero value. Use a pointer field (*int) or json.RawMessage when "not provided" matters.
  • Reuse is risky. Because Unmarshal merges into existing data (maps, pointers, slices with capacity), decode into a fresh variable for each message.
  • Streams: Unmarshal needs the whole document in memory; for large or multiple values use json.Decoder.
  • Untrusted input: deeply nested documents are rejected beyond about 10,000 levels; cap body size yourself.