JSON and Struct Tags in Go: What Every Dev Should Know

May 05, 2025

Introduction

Working with JSON in Go is a fundamental skill that every developer needs to master. Whether you're building REST APIs, consuming external services, or storing configuration data, understanding how Go's struct tags work with JSON marshaling and unmarshaling is crucial. This comprehensive guide will walk you through everything you need to know about JSON struct tags, from basic usage to advanced techniques that will make your Go code more robust and maintainable.

What Are Struct Tags?

Struct tags in Go are string literals that provide metadata about struct fields. They're written as raw string literals (using backticks) and follow the field declaration. The Go runtime and various packages use these tags to control how struct fields are processed during operations like JSON marshaling, database mapping, and validation.

Basic Struct Tag Syntax:

basic-tags.go

type User struct {
    ID       int    `json:"id"`
    Name     string `json:"name"`
    Email    string `json:"email"`
    Password string `json:"-"`        // Excluded from JSON
    Age      int    `json:"age,omitempty"` // Omitted if zero value
}

The tag format follows the pattern: \`key:"value"\`. For JSON, the key is \`json\` and the value specifies how the field should be handled during JSON operations.

Common JSON Tag Options

Go's JSON package supports several tag options that give you fine-grained control over JSON serialization and deserialization.

Field Naming and Exclusion:

json-options.go

type Product struct {
    ID          int     `json:"id"`                    // Custom field name
    ProductName string  `json:"product_name"`         // Snake case naming
    Price       float64 `json:"price"`                // Standard naming
    InternalID  string  `json:"-"`                    // Excluded from JSON
    Discount    float64 `json:"discount,omitempty"`   // Omit if zero value
    Tags        []string `json:"tags,omitempty"`      // Omit if empty slice
    Metadata    map[string]interface{} `json:"metadata,omitempty"` // Omit if nil
}

String Option for Numbers:

string-option.go

type APIResponse struct {
    UserID    int64  `json:"user_id,string"`     // Marshaled as string
    Timestamp int64  `json:"timestamp,string"`  // Useful for large numbers
    Amount    float64 `json:"amount,string"`     // Precision preservation
}

// JSON output:
// {
//   "user_id": "1234567890123456789",
//   "timestamp": "1642694400",
//   "amount": "99.99"
// }

Nested Structs and Embedding

Go handles nested structs and embedded fields elegantly with JSON tags, allowing you to create complex data structures that map cleanly to JSON.

Nested Structs:

nested-structs.go

type Address struct {
    Street  string `json:"street"`
    City    string `json:"city"`
    Country string `json:"country"`
    ZipCode string `json:"zip_code"`
}

type User struct {
    ID      int     `json:"id"`
    Name    string  `json:"name"`
    Email   string  `json:"email"`
    Address Address `json:"address"`           // Nested struct
    WorkAddress *Address `json:"work_address,omitempty"` // Pointer to struct
}

// JSON output:
// {
//   "id": 1,
//   "name": "John Doe",
//   "email": "john@example.com",
//   "address": {
//     "street": "123 Main St",
//     "city": "New York",
//     "country": "USA",
//     "zip_code": "10001"
//   }
// }

Embedded Structs:

embedded-structs.go

type Timestamps struct {
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
}

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
    Timestamps        // Embedded struct - fields promoted to parent
}

// Alternative: Embed with custom JSON key
type Product struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Price float64 `json:"price"`
    Timestamps `json:"timestamps"` // Embedded as nested object
}

// User JSON (fields promoted):
// {
//   "id": 1,
//   "name": "John",
//   "email": "john@example.com",
//   "created_at": "2025-01-20T10:00:00Z",
//   "updated_at": "2025-01-20T10:00:00Z"
// }

// Product JSON (nested object):
// {
//   "id": 1,
//   "name": "Widget",
//   "price": 29.99,
//   "timestamps": {
//     "created_at": "2025-01-20T10:00:00Z",
//     "updated_at": "2025-01-20T10:00:00Z"
//   }
// }

Custom JSON Marshaling

Sometimes struct tags aren't enough, and you need complete control over JSON serialization. Go provides interfaces that allow you to implement custom marshaling logic.

Implementing json.Marshaler and json.Unmarshaler:

custom-marshaling.go

type Status int

const (
    StatusInactive Status = iota
    StatusActive
    StatusSuspended
)

// Custom marshaling for Status
func (s Status) MarshalJSON() ([]byte, error) {
    switch s {
    case StatusInactive:
        return []byte(`"inactive"`), nil
    case StatusActive:
        return []byte(`"active"`), nil
    case StatusSuspended:
        return []byte(`"suspended"`), nil
    default:
        return nil, fmt.Errorf("unknown status: %d", s)
    }
}

// Custom unmarshaling for Status
func (s *Status) UnmarshalJSON(data []byte) error {
    var str string
    if err := json.Unmarshal(data, &str); err != nil {
        return err
    }
    
    switch str {
    case "inactive":
        *s = StatusInactive
    case "active":
        *s = StatusActive
    case "suspended":
        *s = StatusSuspended
    default:
        return fmt.Errorf("unknown status: %s", str)
    }
    return nil
}

type User struct {
    ID     int    `json:"id"`
    Name   string `json:"name"`
    Status Status `json:"status"`
}

// Usage
user := User{ID: 1, Name: "John", Status: StatusActive}
data, _ := json.Marshal(user)
fmt.Println(string(data))
// Output: {"id":1,"name":"John","status":"active"}

Advanced Techniques

Dynamic JSON Field Names:

dynamic-fields.go

// Using map for dynamic fields
type DynamicData struct {
    ID   int                    `json:"id"`
    Data map[string]interface{} `json:"data"`
}

// Using json.RawMessage for deferred parsing
type FlexibleResponse struct {
    Type    string          `json:"type"`
    Payload json.RawMessage `json:"payload"`
}

func (f *FlexibleResponse) ParsePayload(v interface{}) error {
    return json.Unmarshal(f.Payload, v)
}

// Usage
response := FlexibleResponse{
    Type:    "user",
    Payload: json.RawMessage(`{"id":1,"name":"John"}`),
}

var user User
if err := response.ParsePayload(&user); err != nil {
    log.Fatal(err)
}

Conditional JSON Fields:

conditional-fields.go

type User struct {
    ID       int    `json:"id"`
    Name     string `json:"name"`
    Email    string `json:"email"`
    Password string `json:"password,omitempty"`
    IsAdmin  bool   `json:"is_admin,omitempty"`
}

// Custom marshaling for different contexts
func (u User) MarshalJSON() ([]byte, error) {
    type Alias User // Prevent infinite recursion
    
    // Create a copy without sensitive fields
    safe := struct {
        Alias
        Password string `json:"password,omitempty"`
    }{
        Alias: Alias(u),
        // Password is omitted by not setting it
    }
    
    return json.Marshal(safe)
}

// Alternative: Use different structs for different contexts
type UserPublic struct {
    ID      int    `json:"id"`
    Name    string `json:"name"`
    Email   string `json:"email"`
}

type UserPrivate struct {
    UserPublic
    Password string `json:"password"`
    IsAdmin  bool   `json:"is_admin"`
}

func (u User) ToPublic() UserPublic {
    return UserPublic{
        ID:    u.ID,
        Name:  u.Name,
        Email: u.Email,
    }
}

Real-World Example: API Response Handling

Here's a comprehensive example showing how to handle a complex API response with nested data, optional fields, and custom formatting.

api-response.go

package main

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

// Custom time format for API
type APITime struct {
    time.Time
}

func (t APITime) MarshalJSON() ([]byte, error) {
    return []byte(fmt.Sprintf(""%s"", t.Format("2006-01-02T15:04:05Z"))), nil
}

func (t *APITime) UnmarshalJSON(data []byte) error {
    var timeStr string
    if err := json.Unmarshal(data, &timeStr); err != nil {
        return err
    }
    
    parsed, err := time.Parse("2006-01-02T15:04:05Z", timeStr)
    if err != nil {
        return err
    }
    
    t.Time = parsed
    return nil
}

// API response structures
type APIResponse struct {
    Success   bool        `json:"success"`
    Message   string      `json:"message,omitempty"`
    Data      interface{} `json:"data,omitempty"`
    Error     *APIError   `json:"error,omitempty"`
    Timestamp APITime     `json:"timestamp"`
}

type APIError struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Details string `json:"details,omitempty"`
}

type User struct {
    ID        int      `json:"id"`
    Username  string   `json:"username"`
    Email     string   `json:"email"`
    FullName  string   `json:"full_name"`
    Avatar    *string  `json:"avatar"`           // Pointer for nullable field
    Roles     []string `json:"roles,omitempty"`
    Settings  UserSettings `json:"settings"`
    CreatedAt APITime  `json:"created_at"`
    UpdatedAt APITime  `json:"updated_at"`
    LastLogin *APITime `json:"last_login,omitempty"` // Nullable timestamp
}

type UserSettings struct {
    Theme         string `json:"theme"`
    Language      string `json:"language"`
    Notifications bool   `json:"notifications"`
    Privacy       PrivacySettings `json:"privacy"`
}

type PrivacySettings struct {
    ProfileVisible bool `json:"profile_visible"`
    EmailVisible   bool `json:"email_visible"`
}

func main() {
    // Example API response JSON
    jsonData := `{
        "success": true,
        "data": {
            "id": 123,
            "username": "johndoe",
            "email": "john@example.com",
            "full_name": "John Doe",
            "avatar": null,
            "roles": ["user", "moderator"],
            "settings": {
                "theme": "dark",
                "language": "en",
                "notifications": true,
                "privacy": {
                    "profile_visible": true,
                    "email_visible": false
                }
            },
            "created_at": "2025-01-15T10:30:00Z",
            "updated_at": "2025-01-20T14:22:33Z"
        },
        "timestamp": "2025-01-20T15:00:00Z"
    }`
    
    // Parse the response
    var response APIResponse
    if err := json.Unmarshal([]byte(jsonData), &response); err != nil {
        log.Fatal(err)
    }
    
    // Extract user data
    userData, _ := json.Marshal(response.Data)
    var user User
    if err := json.Unmarshal(userData, &user); err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("User: %s (%s)\n", user.FullName, user.Email)
    fmt.Printf("Created: %s\n", user.CreatedAt.Format("2006-01-02"))
    fmt.Printf("Theme: %s\n", user.Settings.Theme)
    fmt.Printf("Roles: %v\n", user.Roles)
    
    // Marshal back to JSON
    output, _ := json.MarshalIndent(user, "", "  ")
    fmt.Println("\nJSON Output:")
    fmt.Println(string(output))
}

Best Practices and Common Pitfalls

✅ Best Practices:

Use omitempty for optional fields to keep JSON clean
Use pointers for nullable fields (*string, *int, etc.)
Implement custom marshaling for complex types (enums, custom time formats)
Use json:"-" to exclude sensitive fields like passwords
Consider using different structs for different API contexts (public vs private)
Use json.RawMessage for deferred parsing of dynamic content
Validate JSON input after unmarshaling

❌ Common Pitfalls:

Forgetting that unexported fields are ignored by JSON package
Not handling nil pointers when using omitempty
Using interface when a specific type would be better
Not validating required fields after unmarshaling
Infinite recursion in custom MarshalJSON methods
Not handling time zones properly in custom time types
Exposing internal struct fields in public APIs

💡 Performance Tips:

Use json.Decoder for streaming large JSON files
Pool JSON encoders/decoders for high-throughput applications
Consider using easyjson or ffjson for performance-critical code
Avoid unnecessary allocations in custom marshal methods
Use struct field ordering to optimize memory layout

Conclusion

Mastering JSON struct tags in Go is essential for building robust applications that interact with APIs, databases, and configuration files. The combination of struct tags, custom marshaling, and Go's type system provides powerful tools for handling complex data transformations while maintaining type safety and performance.

Remember that the key to effective JSON handling in Go is understanding when to use struct tags versus custom marshaling, how to handle optional and nullable fields properly, and how to structure your data types to match your API contracts. With these techniques in your toolkit, you'll be well-equipped to handle any JSON processing challenge that comes your way.

As you continue working with JSON in Go, experiment with different approaches, profile your applications for performance bottlenecks, and always consider the maintainability and readability of your code. The patterns and techniques covered in this guide will serve as a solid foundation for building scalable and maintainable Go applications.