How to convert a struct to JSON in Go

1json.MarshalRecommended

The whole job is one call: func Marshal(v any) ([]byte, error). Hand it a struct (or a pointer to one — Marshal dereferences it) and you get the encoded document back as bytes. Bytes, not a string, because that is what you actually want to hand to w.Write, os.WriteFile or an HTTP body; convert with string(data) only when a human has to read it.

package main

import (
	"encoding/json"
	"fmt"
)

type User struct {
	Name  string
	Email string
	Age   int
	Admin bool
}

func main() {
	u := User{Name: "Ada Lovelace", Email: "[email protected]", Age: 36, Admin: true}

	data, err := json.Marshal(u)
	if err != nil {
		fmt.Println("marshal failed:", err)
		return
	}

	// Marshal hands back bytes, not a string.
	fmt.Printf("%T\n", data)
	fmt.Println(string(data))
}

Prints []uint8 — Go's own name for []byte — and then {"Name":"Ada Lovelace","Email":"[email protected]","Age":36,"Admin":true}. Two things to notice: the keys are the Go field names, capitals and all, which is almost never the JSON you want (section 2 fixes it), and the err is real — encoding a struct of plain fields can't fail, but a channel, a function or a NaN float will, so check it.

2Struct tags: rename, omit, hide

A struct tag is a backtick-quoted string after the field type, and encoding/json reads the json: key out of it. Three forms cover almost everything: json:"name" renames the key, json:"nickname,omitempty" drops the field when its value is the zero value, and json:"-" removes it from the output entirely — the right way to keep a password or an internal ID out of an API response.

package main

import (
	"encoding/json"
	"fmt"
)

type User struct {
	Name     string `json:"name"`
	Email    string `json:"email"`
	Nickname string `json:"nickname,omitempty"` // dropped while empty
	Password string `json:"-"`                  // never encoded
	Age      int    `json:"age,omitempty"`      // 0 counts as empty
}

func main() {
	u := User{Name: "Ada", Email: "[email protected]", Password: "hunter2"}

	plain, _ := json.Marshal(u)
	fmt.Println(string(plain))

	u.Nickname = "The Countess"
	u.Age = 36
	filled, _ := json.Marshal(u)
	fmt.Println(string(filled))

	// The tagged-out fields still exist in Go -- only the JSON drops them.
	fmt.Println(u.Password)
}

The first line is {"name":"Ada","email":"[email protected]"}: no nickname and no age, because both were still zero, and no password ever. Fill them in and the second line becomes {"name":"Ada","email":"[email protected]","nickname":"The Countess","age":36}, while u.Password still prints hunter2 — the tag hides the field from JSON, not from Go. Watch omitempty on booleans and numbers: it treats false and 0 as empty, so a real "age": 0 disappears too. When you must distinguish "zero" from "absent", make the field a pointer (*int) — then only nil is omitted.

3Pretty-print with json.MarshalIndent

json.MarshalIndent(v, prefix, indent) is Marshal plus line breaks. The usual call is json.MarshalIndent(v, "", " ") — no prefix, two spaces per level. The prefix argument is prepended to every line except the first, which is what you want when the block is being pasted into something already indented.

package main

import (
	"encoding/json"
	"fmt"
)

type Config struct {
	Service string   `json:"service"`
	Port    int      `json:"port"`
	Debug   bool     `json:"debug"`
	Tags    []string `json:"tags"`
}

func main() {
	c := Config{Service: "api", Port: 8080, Debug: false, Tags: []string{"go", "prod"}}

	// prefix "", indent two spaces -- the usual choice
	pretty, err := json.MarshalIndent(c, "", "  ")
	if err != nil {
		fmt.Println("marshal failed:", err)
		return
	}
	fmt.Println(string(pretty))

	// A prefix indents every line but the first -- handy when embedding.
	nested, _ := json.MarshalIndent(c, "\t", "  ")
	fmt.Println(string(nested))

	compact, _ := json.Marshal(c)
	fmt.Println(len(pretty), "bytes pretty vs", len(compact), "bytes compact")
}

The first block is the familiar two-space JSON; the second shows the tab prefix pushing every line but the opening brace to the right. The last line prints 94 bytes pretty vs 64 bytes compact — nearly 50% more bytes on this tiny struct, which is why you indent logs, config files and docs but send compact JSON over the wire. Indenting is not free either: it is a second pass over the bytes, so don't reach for it in a hot path.

4Nested structs, slices, maps and time.Time

Marshal recurses, so a struct of structs, slices and maps needs no extra work — a nested struct becomes a nested object, a slice becomes an array, and a map[string]T becomes an object with its keys sorted (that is a documented guarantee, so the output is stable and diffable — no sorting the keys yourself the way you would to range over the map deterministically). time.Time implements json.Marshaler and encodes itself as an RFC 3339 string. The gotchas are on the empty side: a nil slice or map encodes as null, not [] or {}.

package main

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

type Address struct {
	City    string `json:"city"`
	Country string `json:"country"`
}

type Order struct {
	ID    int     `json:"id"`
	Total float64 `json:"total"`
}

type Account struct {
	Name      string            `json:"name"`
	Address   Address           `json:"address"`           // nested struct
	Orders    []Order           `json:"orders"`            // slice of structs
	Limits    map[string]int    `json:"limits"`            // map -- keys are sorted
	Labels    map[string]string `json:"labels"`            // nil map
	Created   time.Time         `json:"created,omitempty"` // omitempty is a no-op here
	DeletedAt *time.Time        `json:"deleted_at"`        // nil pointer
	Referrer  *string           `json:"referrer,omitempty"`
}

func main() {
	a := Account{
		Name:    "Ada",
		Address: Address{City: "London", Country: "GB"},
		Orders:  []Order{{ID: 1, Total: 19.5}, {ID: 2, Total: 4}},
		Limits:  map[string]int{"rps": 100, "burst": 20, "daily": 5000},
		Created: time.Date(2026, time.August, 6, 9, 30, 0, 0, time.UTC),
	}

	out, _ := json.MarshalIndent(a, "", "  ")
	fmt.Println(string(out))

	// Empty values: a nil slice or map is null; an empty non-nil slice is [].
	empty, _ := json.Marshal(Account{Orders: []Order{}})
	fmt.Println(string(empty))
}

The limits map comes out as burst, daily, rps — alphabetical, not the order written. created renders as "2026-08-06T09:30:00Z", the nil *time.Time as null, and referrer vanishes because omitempty plus a nil pointer is the one combination that behaves the way people expect. The last line marshals an almost-empty Account and shows the trap: "limits":null and "labels":null for the untouched maps, but "orders":[] for the slice that was explicitly set to an empty non-nil one. JavaScript clients that loop over the result will happily iterate [] and crash on null, so initialise the slices you intend to send. Look at created on that same line, too: the field is tagged json:"created,omitempty" and the zero time is written out anyway as "0001-01-01T00:00:00Z". omitempty has no notion of an empty struct, so it never drops a time.Time — reach for *time.Time when "no date" has to mean absent.

5Which should you use?

6Streaming with json.NewEncoder

json.NewEncoder(w) writes straight to an io.Writer instead of building a []byte first — that is the idiomatic body of an HTTP handler (json.NewEncoder(w).Encode(resp)) and the way to emit newline-delimited JSON without ever holding the whole stream in memory. Encode appends a \n after each document, which is exactly the NDJSON format. The snippet writes to a bytes.Buffer so the page can show you the bytes; swap it for os.Stdout, a file or an http.ResponseWriter and nothing else changes.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
)

type Event struct {
	ID    int    `json:"id"`
	Stage string `json:"stage"`
}

func main() {
	events := []Event{{1, "queued"}, {2, "building"}, {3, "done"}}

	// An Encoder writes to any io.Writer: os.Stdout, an http.ResponseWriter,
	// a file, or -- so this page can show the bytes -- a buffer.
	var out bytes.Buffer
	enc := json.NewEncoder(&out)
	for _, e := range events {
		if err := enc.Encode(e); err != nil {
			fmt.Println("encode:", err)
			return
		}
	}
	fmt.Print(out.String()) // Encode already appended a newline to each

	// Marshal escapes <, > and & for HTML safety. The encoder can opt out.
	tricky := Event{ID: 4, Stage: "a & b <ok>"}
	escaped, _ := json.Marshal(tricky)
	fmt.Println(string(escaped))

	var raw bytes.Buffer
	rawEnc := json.NewEncoder(&raw)
	rawEnc.SetEscapeHTML(false)
	rawEnc.SetIndent("", "  ")
	rawEnc.Encode(tricky)
	fmt.Print(raw.String())
}

The three events come out one per line, no enclosing array — that is what a log tail or a jq pipeline wants. The fourth line shows the other surprise: json.Marshal escapes <, > and & as \u003c, \u003e and \u0026 so the output is safe to drop inside a <script> tag. It is still valid JSON and decodes back to the same string, but if you need the literal characters, only the encoder can turn it off — enc.SetEscapeHTML(false), shown on the last block together with enc.SetIndent, the encoder's answer to MarshalIndent.