Struct tags in Go are string annotations that control how struct fields are marshaled to and from JSON; 1. Use json:"fieldname" to customize the JSON key name, 2. Add ,omitempty to omit fields with zero values like empty strings or 0, 3. Use pointers with omitempty to handle nullable fields, 4. Use json:"-" to ignore a field entirely during marshaling, 5. Be cautious with omitempty on booleans and numeric fields where zero is a valid value, 6. Apply tags to nested or embedded structs normally, and 7. For complex cases, implement MarshalJSON, but struct tags suffice for most JSON formatting needs, ensuring clean separation between internal structs and external APIs.

In Go, struct tags are a powerful feature that let you control how struct fields are marshaled and unmarshaled to and from JSON. When working with JSON data—such as building APIs or reading configuration files—you’ll often need to customize the field names or behavior during serialization. This is where struct tags come in.

What are struct tags?

Struct tags are string annotations attached to struct fields that provide metadata. For JSON marshaling, the json tag tells the encoding/json package how to handle each field.

Here’s a basic example:

type User struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    Age   int    `json:"age"`
}

When this struct is marshaled to JSON using json.Marshal, the output will use the lowercase field names as specified in the tags:

{"name":"John","email":"john@example.com","age":30}

Without the tags, the field names would still be used as-is (since Go exports fields with capital letters), but they’d appear in JSON as "Name", "Email", etc., which is often not desired in JSON APIs.

Common JSON tag options

The json tag supports several options that modify how fields are handled.

1. Customize field names

You can map a Go field to a different JSON key:

type Product struct {
    ID       int     `json:"product_id"`
    Price    float64 `json:"price_usd"`
    InStock  bool    `json:"in_stock"`
}

This produces:

{"product_id":101,"price_usd":19.99,"in_stock":true}

2. Omit empty fields

Use the omitempty option to exclude fields when they have zero values (e.g., zero, nil, empty string):

type User struct {
    Name  string `json:"name"`
    Email string `json:"email,omitempty"`
    Age   int    `json:"age,omitempty"`
}

If Email is an empty string or Age is 0, those fields will be omitted from the JSON output.

Example:

u := User{Name: "Alice", Email: "", Age: 0}
data, _ := json.Marshal(u)
fmt.Println(string(data))
// Output: {"name":"Alice"}

3. Handle optional or nullable fields with pointers

omitempty works well with pointers or interface types. If a field is a pointer and is nil, it can be omitted.

type User struct {
    Name     string  `json:"name"`
    Nickname *string `json:"nickname,omitempty"`
}

If Nickname is nil, it won’t appear in the output.

4. Ignore fields entirely

Use the - dash to completely ignore a field during JSON marshaling:

type User struct {
    Name string `json:"name"`
    Password string `json:"-"`
}

The Password field won’t be included in the JSON output, even if it has a value.

Advanced use cases

5. Omitting false booleans or zero values

Be careful: omitempty omits fields when they are zero values. For booleans, false is the zero value, so:

type Flags struct {
    IsActive bool `json:"is_active,omitempty"`
}

If IsActive is false, it will be omitted. If you always want the field to appear (as true or false), remove omitempty.

6. Nested structs and embedding

Tags work the same way with nested or embedded structs:

type Address struct {
    City  string `json:"city"`
    Zip   string `json:"zip"`
}

type User struct {
    Name    string  `json:"name"`
    Address Address `json:"address"`
}

Output:

{
  "name": "Bob",
  "address": {
    "city": "Seattle",
    "zip": "98101"
  }
}

7. Custom marshaling with MarshalJSON

For more complex cases (like formatting dates or handling polymorphic types), you can implement the json.Marshaler interface on your type, but struct tags are sufficient for most naming and omission needs.

Key takeaways

• Use json:"fieldname" to control the JSON key name.
• Add ,omitempty to skip zero-value fields.
• Use json:"-" to ignore a field completely.
• Be cautious with omitempty on booleans and numeric fields where zero is a valid value.
• Tags only work on exported (capitalized) fields.

Struct tags are simple but essential for clean JSON handling in Go APIs. They help you separate internal struct design from external JSON representation, making your code more maintainable and your APIs more consistent.

Basically, just remember: tag your exported fields, use omitempty wisely, and test your JSON output.

The above is the detailed content of How to use struct tags for JSON marshaling in Go. For more information, please follow other related articles on the PHP Chinese website!