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.
type User struct { ID int `json:"id"` Email string `json:"email,omitempty"` }
Try it
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.
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 vetreports malformed tags. - Use
omitemptycarefully:Count intjson:",omitempty"`` also hides a legitimate0. Use a pointer (*int) when zero is meaningful, oromitzerofor struct types. stringoption 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.
Related
encoding/json,json.Marshal(),json.Unmarshal(),struct- Lessons: Struct tags, JSON, Embedding