JSON a Go Struct: el generador entrega el esqueleto, cuatro cosas requieren tus manos
En resumen: Pega una respuesta de API de muestra en el convertidor y en diez segundos tienes structs Go con tags — pero los números se convierten en float64, los campos opcionales nunca se convierten en punteros por sí solos, omitempty no elimina structs vacías y la mayoría de las fechas siguen siendo strings. Tabla completa de mapeo, el equilibrio entre puntero y omitzero y una lista de verificación de cuatro pasos para pulir el código generado.

Conclusión primero: las structs que un convertidor produce en diez segundos compilan, pero no están listas para producción. El generador describe solo la única muestra que pegaste — los números se convierten en float64, los campos opcionales nunca se convierten en punteros solos, omitempty no derriba structs vacías, y la mayoría de los strings de fecha siguen siendo strings. Esas cuatro brechas siguen siendo trabajo tuyo después de pegar.
Convertir una respuesta de API en structs Go es trabajo puramente mecánico, y el costo del trabajo mecánico se esconde en el silencio: un nombre de campo mal escrito no genera error de compilación, solo un campo que queda en cero para siempre; un interruptor equivocado en el manejo de null y un
"note": nullaparece en producción donde nadie lo esperaba. La generación de structs resuelve la alineación de nombres y tipos, pero dos cosas nunca se alinean solas: las variantes fuera de tu muestra y el foso entre el sistema de tipos de Go y el de JSON.
Lo que el generador realmente lee: una tabla de mapeo
Todo convertidor JSON → Go corre sobre la misma tabla. Pasa una respuesta típica de pedido por la página /convert/go de este sitio — pega la muestra, activa los tags json — y obtienes esta forma:
| Valor JSON | Tipo Go generado | Notas |
|---|---|---|
| string | string |
Los strings de fecha normalmente siguen siendo strings, ver time.Time abajo |
| entero | float64 |
encoding/json analiza los números internamente como double |
| decimal | float64 |
Cambia los campos monetarios por librería decimal o int64 en unidades menores |
| true / false | bool |
Sin trampas |
| null | any |
Una sola muestra null no prueba nada, fallback conservador |
| objeto | struct nombrada | Los objetos anidados se convierten en su propia struct |
objeto vacío {} |
map[string]any |
Ningún campo observable, el generador no adivina |
| array | []TipoElemento |
Tipo del elemento inferido de la primera muestra |
| tipos mixtos | any |
Go no tiene uniones, campos con múltiples tipos caen en any |
// Muestra de entrada
// {"id":"A-1029","items":[{"sku":"J-01","qty":2}],"coupon":null}
type Root struct {
ID string `json:"id"`
Items []Item `json:"items"`
Coupon any `json:"coupon"`
}
type Item struct {
Sku string `json:"sku"`
Qty int `json:"qty"`
}
Tres observaciones. El objeto anidado items se convirtió en su propia struct Item referenciada por un slice. coupon solo apareció como null: el generador no puede probar qué será después y cae en any. El número qty aterriza como int o float64 según la herramienta — las estrategias difieren, pero todas se apoyan en la misma suposición: la muestra es toda la verdad.
Tags json: nombres originales, opciones y tres errores fáciles
Los tags cargan la mayor densidad de información en la salida del generador y también son la parte más fácil de equivocar al ajustar. Las reglas vienen directamente de la documentación de encoding/json:
Field int `json:"myName"` // aparece bajo la clave myName
Field int `json:"myName,omitempty"` // campo entero omitido cuando vacío
Field int `json:",omitempty"` // nombre de campo por defecto, solo la opción
Field int `json:"-"` // siempre ignorado, sin codificar ni decodificar
Field int64 `json:"id,string"` // número codificado dentro de un string
Tres descuidos que vale la pena memorizar. Primero, la coma inicial en json:",omitempty" — cuando quieres solo saltar valores vacíos sin renombrar la clave, la coma es obligatoria; sin ella, el campo se trata como una clave literalmente llamada ,omitempty. Segundo, mantén la clave JSON original en el tag (user_id, html_url) mientras el campo Go usa la convención idiomática (UserID, HTMLURL): sin tag, la correspondencia usa el nombre del campo literalmente, así que una clave userId en la respuesta nunca mapea, silenciosamente. Tercero, además de json:"-" existe json:"-," — este último significa que la clave realmente se llama -.
Punteros: nil es la única forma de distinguir "ausente" de "cero"
El sistema de valores cero de Go impide que int y string expresen "campo no presente" — 0 y "" pueden ser datos reales o simplemente no analizados. La misma clave JSON tiene tres estados: presente con valor, presente como null y ausente. Los tipos por valor cubren solo el primero.
type Config struct {
Note string `json:"note,omitempty"` // omitido solo cuando exactamente ""
Alias *string `json:"alias,omitempty"` // omitido cuando nil
Details *Meta `json:"details,omitempty"`
}
El valor cero de un campo puntero es nil. json.Unmarshal lo deja nil cuando la clave falta o es null, y omitempty lo salta solo en ese caso. Por eso la mayoría de los convertidores ofrecen un interruptor "usar punteros para objetos anidados": activado, las structs anidadas se convierten en *Item, y en una petición PATCH "campo no enviado" y "null enviado para eliminar" finalmente se separan. El precio son comprobaciones de nil por todas partes — p.Address.Street entra en pánico cuando Address es nil, uno de los crashes de runtime más comunes en código JSON en Go.
La struct vacía que omitempty no puede derribar, y el hueco que omitzero llena
La definición oficial de omitempty juzga valores: false, 0, punteros nil, interfaces nil y arrays, slices, maps o strings de longitud cero. Nota lo que no está en la lista: structs vacías.
type Order struct {
Meta Meta `json:"meta,omitempty"`
}
type Meta struct {
Version string
Build int
}
// Meta{Version: "1.0"} → "meta":{"version":"1.0","build":0}
// Meta{} → "meta":{} ← omitempty no hizo nada
Un campo struct nunca es omitido por omitempty — vive en memoria como un contenedor de tamaño fijo, y un contenedor existente no está "vacío". La corrección es convertir el campo en *Meta; solo un puntero nil se descarta. Desde Go 1.24 existe un segundo interruptor, omitzero: juzgado por el valor cero de Go, llamando IsZero() bool cuando el tipo lo define — la única forma de omitir un time.Time cero. Con encoding/json/v2 (experimental en Go 1.25) la semántica se desplaza de nuevo: el omitempty de v2 juzga el resultado JSON codificado (solo null, "", {}, [] cuentan como vacío), así que count: 0 permanece en la salida; al migrar código antiguo, el omitempty en campos bool y numéricos debe convertirse en omitzero para conservar el significado original.
Todo número se convierte en float64: la trampa de los enteros grandes
Sin tipo explícito, el decoder de encoding/json trata los números como float64, y float64 tiene solo 53 bits de mantisa. El caso clásico de JavaScript — 9007199254740993 convirtiéndose en 9007199254740992 — existe también en Go, siempre que el campo destino sea float64 o any.
var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] es float64(9007199254740992), precisión ya perdida
Tres salidas. Declara el campo de la struct como int64 y el decoder analiza exactamente en él. Cuando necesites pasar por any, llama decoder.UseNumber() para que los números aterricen como strings json.Number que conviertes deliberadamente. Nunca uses punto flotante para dinero — guarda unidades menores en int64 o usa una librería decimal. Siempre que una API devuelva IDs snowflake o números de pedido de 64 bits, esta sección es comprobación obligatoria.
time.Time solo acepta RFC 3339
Ante "2024-01-15T10:30:00Z" un generador mapea time.Time; ante "2024-01-15 10:30:00" deja un string. No es pereza — es una restricción dura de encoding/json: time.Time implementa UnmarshalJSON y analiza estrictamente en el layout RFC 3339 2006-01-02T15:04:05Z07:00. T faltante, zona horaria faltante o una Z seguida de offset todos fallan:
parsing time "\"2022-07-27T14:16:00Z04:00\"" as
"\"2006-01-02T15:04:05Z07:00\"": cannot parse "04:00\"" as "\""
Cuando el formato de upstream no puede cambiar, la corrección estándar es un tipo personalizado que envuelve time.Time y cuyo UnmarshalJSON intenta varios layouts:
type CustomDate struct{ time.Time }
func (c *CustomDate) UnmarshalJSON(b []byte) error {
s := strings.Trim(string(b), `"`)
t, err := time.Parse("2006-01-02 15:04:05", s)
if err != nil {
t, err = time.Parse(time.RFC3339, s)
if err != nil {
return fmt.Errorf("invalid date format: %w", err)
}
}
c.Time = t
return nil
}
La lista de verificación de cuatro pasos después de generar
Cuatro pasos separan la salida del generador del código de producción, y recorrerlos una vez cuesta menos que depurar después:
- Reemplaza cada fallback any: busca
any, revisa tres a cinco muestras reales por campo en fallback y luego aterriza en un tipo concreto o puntero; - Reverifica las anchuras numéricas: mueve IDs, montos y contadores de float64 a int64 / int32 / decimal; en duda sobre la anchura, escribe int64;
- Marca la opcionalidad: punteros o omitempty/omitzero para campos de objetos en arrays, cuerpos PATCH y campos anulables de APIs de terceros — decide la semántica de nil una vez, aquí;
- Compila y prueba la ida y vuelta: ejecuta
go vet, luego agrega un test de ida y vuelta Marshal→Unmarshal para fijar el formato en el cable — eso atrapa la deriva de comportamiento de futuras actualizaciones de encoding/json.
De la muestra al contrato: la frontera del convertidor
Un convertidor responde "cómo se ve esta muestra", no "cómo se verá siempre esta interfaz". Las herramientas competidoras lo dicen francamente en sus propias documentaciones: una muestra no puede probar las variantes de producción — opcionalidad, formatos de fecha y valores de enumeración requieren revisión humana. Así que construye el hábito: antes de pegar, reúne las respuestas más propensas a exponer diferencias (lista vacía, todos los campos, una con nulls); después de generar, trata la salida como borrador, no como entrega. Si la interfaz tiene un documento de contrato, haz explícitas las restricciones con JSON Schema y alinea el código generado con él — vence a la inferencia desde muestras por un orden de magnitud. Para la vista transversal del mismo problema, el lado Java está cubierto en nuestra prueba del generador Java, el contrato frontend en las interfaces TypeScript; el foso de precisión numérica reaparece en cada lenguaje con otro disfraz, detallado en la trampa de números grandes del JSON.
¿Qué campos todavía necesitan revisión manual después de generar?
Al menos cuatro: fallbacks any, anchuras numéricas (float64 → int64), convertir en punteros los campos opcionales y si los campos de fecha deben ser string o time.Time. Los cuatro son variantes de producción invisibles en la muestra; el generador no adivina, el humano debe completar.
¿Por qué mi campo sigue apareciendo en el JSON después de añadir omitempty?
omitempty solo salta valores cero: false, 0, "", nil, slices vacías. Una struct vacía {} no es un valor cero, así que sobrevive — convierte el campo en puntero. Un time.Time cero necesita omitzero, no omitempty.
¿Por qué mi ID entero grande cambió después de la deserialización?
Sin tipo explícito, encoding/json analiza los números como float64, que lleva 53 bits de mantisa; los enteros más allá de 2^53 pierden precisión. Tipa el campo como int64, o llama UseNumber() para conservar los números como json.Number.
¿Cuándo un campo de objeto anidado debe ser puntero?
Dos casos: el campo puede estar ausente o ser null (nil separa "no enviado" de "valor cero"), y una petición PATCH necesita distinguir "no enviado" de "null enviado para eliminar". En structs de respuesta comunes con campos no anulables, los tipos por valor son más seguros — paga el costo de las comprobaciones de nil solo cuando realmente necesites la distinción.