| JSON Data Representation | Inferred Go Type | Golang Package | Allocation / Usage Note |
42 | int | builtin | Platform-sized (32/64-bit); fine for counts |
-7 | int | builtin | Signed; negative values are valid |
2147483647 | int32 | builtin | Fixed 32-bit; overflow errors on Unmarshal |
9007199254740993 | int64 | builtin | Above 2^53; use for IDs and counters |
1700000000 (Unix seconds) | int64 | builtin, time | Convert with time.Unix(v,0) |
1700000000000 (Unix ms) | int64 | builtin, time | Convert with time.UnixMilli(v) |
255 | uint8 | builtin | Byte-sized unsigned; rejects negatives |
65535 | uint16 | builtin | Ports, small enums |
4294967295 | uint32 | builtin | Unsigned 32-bit |
18446744073709551615 | uint64 | builtin | Exact in Go, lossy in JavaScript |
3.14 | float64 | builtin | Default Go type for JSON decimals |
1.5 | float32 | builtin | Half the memory, lower precision |
1e9 | float64 | builtin | Exponent notation decodes as float |
0 | int | builtin | Zero value; dropped by omitempty |
19.99 (money) | int64 (cents) | builtin | Avoid float for currency; store minor units |
12345678901234567890123 | *big.Int | math/big | Arbitrary precision; implements TextUnmarshaler |
| Number kept as text | json.Number | encoding/json | Use with dec.UseNumber() |
true | bool | builtin | Zero value is false |
false | bool | builtin | Cannot tell false from missing; use *bool |
"text" | string | builtin | UTF-8; invalid bytes become U+FFFD |
"" | string | builtin | Empty string is the zero value |
"2026-10-26T20:25:00Z" | time.Time | time | RFC3339 parsed automatically |
"2026-10-26T20:25:00+05:30" | time.Time | time | Offset preserved in Location |
"2026-10-26" | string | builtin, time | Date-only fails time.Time; parse with layout 2006-01-02 |
"20:25:00" | string | builtin | Time of day; no stdlib type |
"1h30m" | time.Duration | time | Needs custom UnmarshalJSON |
"550e8400-e29b-41d4-a716-446655440000" | uuid.UUID | github.com/google/uuid | Or plain string without dependency |
"dev@example.com" | string | builtin, net/mail | Validate with mail.ParseAddress |
"https://example.com" | string | builtin, net/url | Parse later with url.Parse |
"192.168.1.1" | net.IP | net | Implements TextUnmarshaler |
"SGVsbG8=" | []byte | builtin | Standard base64 decoded automatically |
"#ff0000" | string | builtin | No native color type |
null | interface{} / any | builtin | Type unknown; assert at runtime |
null in string field | *string | builtin | nil means null or absent |
null in number field | *int | builtin | Separates 0 from null |
null in boolean field | *bool | builtin | Tri-state: true, false, nil |
null in object field | *Address | builtin | Pointer to sub-struct |
| Optional string | *string + omitempty | builtin | Omitted when nil, kept when empty |
| Optional int (0 is valid) | *int + omitempty | builtin | Pointer to 0 is still emitted |
| Optional decimal | *float64 | builtin | nil when absent |
| Optional boolean | *bool | builtin | Needed for PATCH payloads |
| Optional nested object | *Profile | builtin | nil avoids empty-object output |
| Optional timestamp | *time.Time | time | Pair with omitempty or omitzero |
{} | struct{} | builtin | Zero-size; or map[string]any |
{"a":1,"b":2} fixed keys | struct | builtin | Fastest; keys known at compile time |
{"a":1,"b":2} dynamic keys | map[string]int | builtin | Key order not preserved |
{"k":"v"} | map[string]string | builtin | Headers, labels, env vars |
| Mixed-value object | map[string]interface{} | builtin | Numbers decode as float64 |
{"a":{"x":1}} | map[string]map[string]int | builtin | Nested maps allocate per level |
| Nested object | Named struct | builtin | Reusable and testable |
| Single-use nested object | Anonymous struct{...} | builtin | Inline; cannot be reused |
| Deferred or polymorphic object | json.RawMessage | encoding/json | Zero-copy until decoded again |
[] | []interface{} | builtin | Element type unknown |
["a","b"] | []string | builtin | Grows dynamically |
[1,2,3] | []int | builtin | Use []int64 for large IDs |
[1.5,2] | []float64 | builtin | Mixed int and float widen to float64 |
[true,false] | []bool | builtin | Flags |
[{...},{...}] | []Item | builtin | Contiguous memory; copies on append |
[{...},{...}] (large) | []*Item | builtin | Shared or mutated elements |
[[1,2],[3]] | [][]int | builtin | Jagged matrix |
[1,"a",null] | []interface{} | builtin | Type-switch each element |
[1,"a"] tuple | []json.RawMessage | encoding/json | Decode each index separately |
[10.5,20.1] fixed length | [2]float64 | builtin | Array; extra items are dropped |
["a","b"] unique set | map[string]struct{} | builtin | Needs custom UnmarshalJSON |
"active" enum | type Status string | builtin | Add consts and a validating Unmarshal |
"123" quoted number | int64 + ,string | encoding/json | Common in JS-safe APIs |
"true" quoted bool | bool + ,string | encoding/json | Tag option handles quoting |
Key "$ref" | Ref string | builtin | Tag json:"$ref" maps odd keys |
Key "user-name" | UserName string | builtin | Tag required for dashes |
| String or number value | Custom type | encoding/json | Implement UnmarshalJSON |