Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Encoding and Data Formats

JSON struct tags in Go

Learn Go's json struct tag options: renaming fields, omitempty, omitzero, the string option, skipping with dash, embedded structs and how conflicts are resolved.

A struct tag is a string literal after a field that carries metadata for packages such as encoding/json. The key json controls the field's name and encoding: Name string `json:"name,omitempty"` . The part before the first comma is the JSON key; the words after it are options.

Without a tag, the key is the Go field name exactly as written (UserID), and decoding matches keys case-insensitively. Fields that are not exported are always ignored, with or without a tag.

Go
type User struct {
    ID    int    `json:"id"`
    Email string `json:"email,omitempty"`
}

Try it

Go Renaming, omitting and skipping

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 omitzero, string and embedding

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.

How tags work

The tag syntax is json:"key,option1,option2". Several packages can share one tag string, separated by spaces: json:"id" xml:"id,attr" db:"id". Always use double quotes inside the backticks.

Tag Effect
json:"name" Use name as the key.
json:",omitempty" Keep the Go name, add an option.
json:"-" Never encode or decode this field.
json:"-," Use a real key called -.
omitempty Skip when the value is false, 0, a nil pointer or interface, an empty array, slice, map or string. Structs are never "empty".
omitzero Skip when the value is the type's zero value, or when its IsZero() bool method returns true (Go 1.24). Works for structs such as time.Time.
string Encode a number, bool or string field as a JSON string ("42", "true"). Decoding expects that quoted form.
inline-style embedding An untagged embedded struct's fields join the parent object; a tagged one becomes a nested object.

Usage notes

  • Conflicts: if two fields end up with the same JSON key at the same nesting depth, both are ignored silently, unless exactly one has an explicit tag name, which wins. A shallower field beats a deeper (embedded) one.
  • Spelling mistakes are silent. json: "id" (with a space) or single quotes make the tag invalid and Go falls back to the field name. go vet reports malformed tags.
  • Use omitempty carefully: Count int json:",omitempty"`` also hides a legitimate 0. Use a pointer (*int) when zero is meaningful, or omitzero for struct types.
  • string option is for 64-bit IDs that JavaScript clients would round; it only applies to strings, floats, integers and bools, not to slices or structs.
  • Unexported embedded structs: fields of an unexported embedded struct type are still promoted if the fields themselves are exported.
  • Case: decoding matches "Name", "name" and "NAME" to the same field; encoding always uses the tag spelling.
  • Reading tags yourself: reflect.TypeOf(v).Field(i).Tag.Get("json") returns the raw string.