JSON en Golang: Marshal, Unmarshal y struct tags

Marshal y Unmarshal

json.Marshal convierte un valor Go en bytes JSON. json.Unmarshal rellena un valor Go a partir de bytes JSON. Los struct tags eligen los nombres de los campos JSON.

package main

import (
	"encoding/json"
	"fmt"
)

type User struct {
	ID    int      `json:"id"`
	Name  string   `json:"name"`
	Email string   `json:"email,omitempty"`
	Tags  []string `json:"tags"`
}

func main() {
	u := User{ID: 1, Name: "Ada", Tags: []string{"admin"}}

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

	var back User
	input := []byte(`{"id": 2, "name": "Linus", "email": "l@example.com", "tags": ["kernel", "git"]}`)
	if err := json.Unmarshal(input, &back); err != nil {
		fmt.Println("unmarshal:", err)
		return
	}
	fmt.Printf("%+v\n", back)
}

Email falta en la primera salida por omitempty y un string vacío. Unmarshal necesita un puntero (&back); pasar el valor directamente devuelve un InvalidUnmarshalError.

Struct tags

La sintaxis del tag es json:"name,option,option".

package main

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

type Account struct {
	ID        int       `json:"id"`
	Password  string    `json:"-"`
	Nickname  string    `json:"nickname,omitempty"`
	Balance   int64     `json:"balance,string"`
	CreatedAt time.Time `json:"created_at,omitempty"` // omitempty never omits a struct
	DeletedAt time.Time `json:"deleted_at,omitzero"`  // Go 1.24: omitted when zero
	internal  string    // unexported: always ignored
}

func main() {
	a := Account{ID: 7, Password: "hunter2", Balance: 1500, internal: "x"}
	out, err := json.MarshalIndent(a, "", "  ")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(out))
}

La contraseña nunca sale del struct, el saldo va entre comillas y deleted_at desaparece mientras que created_at imprime el tiempo cero 0001-01-01T00:00:00Z. Esa diferencia es la razón de que se añadiera omitzero: omitempty nunca ha funcionado con structs, y con time.Time es una sorpresa de toda la vida. En Go 1.23 y anteriores, usa un *time.Time con omitempty para conseguir el mismo efecto.

MarshalIndent(v, prefix, indent) produce una salida legible. Úsalo para archivos de configuración y para depurar; las APIs suelen enviar JSON compacto.

Solo campos exportados

encoding/json usa reflexión y solo puede ver los campos exportados. Es el bug de JSON más común en Go:

type point struct {
	x, y int // lowercase: json.Marshal(point{1, 2}) gives {}
}

Ni error ni aviso, solo {} a la salida y campos que se quedan a cero a la entrada. Pon los campos en mayúscula y añade tags para las claves en minúscula.

Cómo empareja los campos la decodificación

Al deserializar en un struct:

• Las claves se emparejan con el nombre del tag, o con el nombre del campo, sin distinguir mayúsculas y minúsculas. {"NAME": "x"} rellena un campo con el tag json:"name".
• Las claves sin campo correspondiente se ignoran en silencio.
• Los campos sin clave correspondiente conservan su valor actual. Unmarshal no los reinicia, así que decodificar en un struct que ya tiene datos los mezcla.
• Un tipo que no coincide (un string donde el struct tiene un int) devuelve un *json.UnmarshalTypeError, pero los demás campos se rellenan igualmente.

Para rechazar claves inesperadas, por ejemplo en una API estricta o en un archivo de configuración con erratas, usa un Decoder con DisallowUnknownFields:

package main

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

type Config struct {
	Port  int  `json:"port"`
	Debug bool `json:"debug"`
}

func main() {
	input := `{"port": 8080, "debgu": true}` // typo in "debug"

	var lenient Config
	err := json.Unmarshal([]byte(input), &lenient)
	fmt.Printf("Unmarshal: %+v, err=%v\n", lenient, err)

	var strict Config
	dec := json.NewDecoder(strings.NewReader(input))
	dec.DisallowUnknownFields()
	err = dec.Decode(&strict)
	fmt.Println("Decoder:", err)

	var typed Config
	err = json.Unmarshal([]byte(`{"port": "8080"}`), &typed)
	fmt.Println("type mismatch:", err)
}

Estructura desconocida: map[string]any

Cuando no conoces la forma de antemano, decodifica en map[string]any o en any. La correspondencia es fija:

package main

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

func main() {
	input := `{"name": "widget", "price": 9.5, "stock": 3, "tags": ["a", "b"], "meta": {"id": 9007199254740993}}`

	var m map[string]any
	if err := json.Unmarshal([]byte(input), &m); err != nil {
		fmt.Println(err)
		return
	}

	name, _ := m["name"].(string)
	stock, _ := m["stock"].(float64) // numbers are float64, even 3
	tags, _ := m["tags"].([]any)
	fmt.Println(name, int(stock), len(tags))

	meta := m["meta"].(map[string]any)
	fmt.Printf("id as float64: %.0f\n", meta["id"]) // precision lost

	// UseNumber keeps numbers as json.Number (a string) for exact handling.
	dec := json.NewDecoder(strings.NewReader(input))
	dec.UseNumber()
	var exact map[string]any
	if err := dec.Decode(&exact); err != nil {
		fmt.Println(err)
		return
	}
	id, err := exact["meta"].(map[string]any)["id"].(json.Number).Int64()
	fmt.Println("id with UseNumber:", id, err)
}

En la salida se ven dos trampas. Todos los números son float64, así que m["stock"].(int) fallaría. Y los enteros por encima de 2^53 pierden precisión como float64: el id 9007199254740993 vuelve como ...992. UseNumber evita las dos.

Si conoces parte de la estructura, decodifica esa parte en un struct y usa json.RawMessage para el resto. Guarda los bytes en bruto de un campo para que puedas decodificarlo más tarde, cuando sepas su tipo.

Slices, maps, punteros y nil

La diferencia entre slice nil y slice vacío importa a los clientes de una API que esperan un array. Inicializa con []T{} o make([]T, 0) cuando el campo tenga que ser [].

Usa un campo puntero (*int, *bool) cuando necesites distinguir "ausente" de "cero" en la entrada. Tras deserializar, un puntero nil significa que la clave faltaba o era null; un puntero a 0 significa que el cliente envió 0.

Streams: Encoder y Decoder

json.Marshal y Unmarshal trabajan con slices de bytes completos. Para un io.Reader o un io.Writer (el body de una petición HTTP, un archivo, stdin), usa json.NewDecoder y json.NewEncoder. Un Decoder también puede leer una secuencia de valores JSON de uno en uno:

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"os"
	"strings"
)

type Event struct {
	Type string `json:"type"`
	N    int    `json:"n"`
}

func main() {
	// Newline-delimited JSON, as in log files and many streaming APIs.
	stream := `{"type":"click","n":1}
{"type":"view","n":2}
{"type":"click","n":3}`

	dec := json.NewDecoder(strings.NewReader(stream))
	clicks := 0
	for {
		var e Event
		err := dec.Decode(&e)
		if errors.Is(err, io.EOF) {
			break
		}
		if err != nil {
			fmt.Println("decode:", err)
			return
		}
		if e.Type == "click" {
			clicks++
		}
	}
	fmt.Println("clicks:", clicks)

	enc := json.NewEncoder(os.Stdout)
	enc.SetEscapeHTML(false) // keep <, > and & readable
	enc.SetIndent("", "  ")
	if err := enc.Encode(map[string]any{"clicks": clicks, "note": "a < b & c"}); err != nil {
		fmt.Println("encode:", err)
	}
}

Encoder.Encode escribe un salto de línea detrás de cada valor. Por defecto, tanto Marshal como Encoder escapan <, > y & como \u003c, \u003e y \u0026, para que el JSON se pueda incrustar con seguridad en HTML. SetEscapeHTML(false) lo desactiva. En los handlers HTTP, json.NewDecoder(r.Body).Decode(&v) y json.NewEncoder(w).Encode(v) son la pareja habitual.

Codificación personalizada

Un tipo puede controlar su propio JSON implementando json.Marshaler y json.Unmarshaler. Un caso habitual es un enum con iota que debe aparecer como nombre, no como número:

package main

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

type Level int

const (
	Low Level = iota
	High
)

var levelNames = []string{"low", "high"}

func (l Level) MarshalJSON() ([]byte, error) {
	return json.Marshal(levelNames[l])
}

func (l *Level) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}
	for i, name := range levelNames {
		if strings.EqualFold(s, name) {
			*l = Level(i)
			return nil
		}
	}
	return fmt.Errorf("unknown level %q", s)
}

type Alert struct {
	Msg   string `json:"msg"`
	Level Level  `json:"level"`
}

func main() {
	out, _ := json.Marshal(Alert{Msg: "disk full", Level: High})
	fmt.Println(string(out))

	var a Alert
	err := json.Unmarshal([]byte(`{"msg":"cpu","level":"LOW"}`), &a)
	fmt.Printf("%+v %v\n", a, err)

	err = json.Unmarshal([]byte(`{"msg":"cpu","level":"urgent"}`), &a)
	fmt.Println(err)
}

MarshalJSON tiene un receptor por valor para que funcione tanto con valores como con punteros; UnmarshalJSON necesita un receptor puntero porque modifica el valor. Los tipos que solo necesitan una forma de string pueden implementar encoding.TextMarshaler (MarshalText), lo que además permite usarlos como claves de map.

Errores comunes

• Nombres de campo en minúscula. Se saltan en silencio.
• Pasar un valor a Unmarshal. Necesita un puntero.
• Ignorar el error. El JSON mal formado y los tipos que no coinciden solo se informan a través de él.
• Suponer que los números de map[string]any son int. Son float64.
• Esperar que omitempty quite un struct vacío o un time.Time a cero. Usa omitzero en Go 1.24, o un puntero.
• Depender del orden de los campos en los maps. Las claves de un map se ordenan en la salida; los campos de un struct mantienen su orden de declaración.