How do you encode/decode JSON in Go?

Question

Accepted Answer

Go's standard library **`encoding/json`** package handles JSON serialization (marshaling) and deserialization (unmarshaling), mapping between Go structs and JSON. **Struct tags** control the field naming, and it's the backbone of most Go web APIs.

## Marshaling: Go struct → JSON

```go
type User struct {
    Name    string `json:"name"`              // tag maps the field to a JSON key
    Email   string `json:"email"`
    Age     int    `json:"age,omitempty"`     // omitempty → skip if zero/empty
    private string                             // unexported → NOT serialized (lowercase)
}

u := User{Name: "Ann", Email: "ann@x.com", Age: 30}
data, err := json.Marshal(u)
fmt.Println(string(data))   // {"name":"Ann","email":"ann@x.com","age":30}
```

`json.Marshal` converts a struct to JSON bytes. **Only exported (capitalized) fields are serialized** — unexported fields are skipped.

## The role of struct tags

```go
type Product struct {
    ID    int    `json:"id"`                  // → "id"
    Name  string `json:"product_name"`        // → "product_name" (rename)
    Price float64 `json:"price,omitempty"`     // omit if 0
    Notes string `json:"-"`                    // "-" → NEVER serialize this field
}
```

Without tags, JSON keys default to the exact (capitalized) field name. Tags let you control the JSON key name, omit empty values (`omitempty`), and exclude fields entirely (`-`) — essential for matching API conventions (e.g. snake_case JSON).

## Unmarshaling: JSON → Go struct

```go
jsonData := []byte(`{"name":"Bob","email":"bob@x.com","age":25}`)

var user User
err := json.Unmarshal(jsonData, &user)   // pass a POINTER to populate it
if err != nil { log.Fatal(err) }
fmt.Println(user.Name)   // "Bob"
```

`json.Unmarshal` parses JSON into a struct — you must pass a **pointer** so it can populate the struct. Fields are matched by tag/name (case-insensitively).

## Working with unknown/dynamic JSON

```go
// when the structure is unknown, unmarshal into a map or interface{}
var result map[string]interface{}
json.Unmarshal(data, &result)
name := result["name"].(string)        // type-assert the value (JSON numbers → float64!)
```

## Streaming with Encoder/Decoder (for I/O)

```go
// encode directly to an io.Writer (e.g. an HTTP response) — efficient, no intermediate buffer
json.NewEncoder(w).Encode(user)

// decode directly from an io.Reader (e.g. an HTTP request body)
json.NewDecoder(r.Body).Decode(&user)
```

For web servers, `Encoder`/`Decoder` work directly with streams (request/response bodies) — the common pattern in handlers.

## Why it matters

JSON encoding/decoding is fundamental to virtually all Go web development — REST APIs, microservices, and configuration all rely on converting between Go structs and JSON.

The `encoding/json` package (standard library, no dependency) is the standard tool, and understanding it well is essential everyday knowledge: how marshaling/unmarshaling work, the critical rule that **only exported fields are serialized**, and especially **struct tags** (controlling JSON key names with `json:"..."`, `omitempty` to skip empty values, `-` to exclude) which are needed to match real-world API conventions like snake_case.

Knowing to pass a pointer to `Unmarshal`, handle dynamic JSON via maps/`interface{}` (with the gotcha that JSON numbers decode to `float64`), and use streaming `Encoder`/`Decoder` for HTTP bodies covers the practical needs of building APIs.

It's a constant, practical part of Go backend work.