Which Go types does json.Marshal encode as something other than their obvious JSON counterpart?

## The default mapping When you hand `json.Marshal` a value, it walks it with reflection and applies a mapping that is mostly what you would guess: - struct → object, fields in declaration order, using the Go field name unless a tag says otherwise - map → object - slice, array → array - string → string - all integer and floating-point kinds → number - bool → `true` / `false` - pointer, interface → whatever it points at, or `null` when nil The interesting part is the handful of places where the guess is wrong. ## Byte slices become base64 `[]byte` is deliberately special-cased: it encodes as a base64 string using the standard alphabet, not as an array of small numbers. The reasoning is that a byte slice usually holds opaque binary — a hash, a blob, a ciphertext — and an array of a few thousand numbers would be both huge and useless to a consumer. Decoding is symmetric: a base64 string decodes back into a `[]byte`. The special case is on the slice, not on the element type. A fixed-size array of bytes has a different Go type and takes the generic array path: ```go type Blob struct { Data []byte Fixed [3]byte } // {"Data":"aGk=","Fixed":[1,2,3]} ``` That asymmetry surprises people who assume the rule is about bytes rather than about the `[]byte` type. ## Nil is visible on the wire Go has two empty slices: a nil one (`var s []T`) and an empty non-nil one (`s := []T{}`). They behave identically in almost all Go code — both have length zero, both can be appended to, both can be ranged over — but they encode differently. A nil slice writes `null`; an empty non-nil slice writes `[]`. The same holds for maps: nil writes `null`, empty writes `{}`. This is the single most common real-world bite in this area. A list endpoint that builds its result with `var items []Item` and never appends anything sends `{"items":null}`, and a client that iterates the field without a null check breaks. The fix is to initialise the slice — `items := []Item{}` — so that "no results" is an empty array rather than an absent value. ## Map keys are always strings JSON object keys are strings by definition, so a Go map key has to be turned into one. Marshal accepts a string-kind key directly, and it accepts any integer-kind key by formatting it and quoting it: `map[int]string{7: "x"}` becomes `{"7":"x"}`. Note that this is lossy in one direction only in the sense that the key comes back as a string on any consumer that is not Go; decoding back into `map[int]string` works because the decoder parses the quoted key. A map key type that is neither of those and carries no textual representation is rejected outright rather than guessed at. Map keys are also sorted when marshaled, which makes output deterministic — handy for golden-file tests, and a reason a decode-then-encode round trip through a map does not reproduce the original key order. ## Aliases hide their identity `rune` is an alias for `int32` and `byte` is an alias for `uint8`. The encoder sees only the underlying kind, so a `rune` field carrying `'A'` encodes as `65`, not as `"A"`. If you want a character on the wire, use a `string`. Similarly, a named type whose underlying type is a string still encodes as a string, and a named integer type used as an enum encodes as its number — the identifier name never reaches the document. Anything that appears on the wire in a different shape from its underlying kind, such as `time.Time` encoding as an RFC 3339 string, does so because that type supplies its own encoding rather than because the default mapping knows about it. ## Why this matters more than it looks Every item above is a place where the Go type and the wire type disagree, and the wire type is what other teams and other languages actually consume. A field's Go type is an internal choice you can change; the shape it produces on the wire is a contract. Reading the mapping once, and writing a test that asserts the exact bytes for one representative struct, is far cheaper than discovering the base64 or the `null` from a consumer's bug report.