Base64 and Hex Codecs

## The problem JSON leaves you with JSON defines exactly six value kinds: object, array, string, number, boolean and null. There is no byte-string type. Anything binary — a hash, a digest, an encrypted token, a small image — has to be *armoured* into characters before it can travel inside a JSON document. `encoding/json` makes that decision for you. When it meets a value whose type is a slice of `byte` (that is, `[]byte`, or any named type whose underlying type is `[]uint8`), it writes a JSON **string** containing the **base64** encoding of the bytes, and it uses `base64.StdEncoding`: the RFC 4648 standard alphabet `A–Z a–z 0–9 + /`, padded with `=` so the length is a multiple of four. ```go type Blob struct { Digest []byte } // json.Marshal(Blob{Digest: []byte("hi")}) -> {"Digest":"aGk="} ``` Unmarshaling is the mirror image: a JSON string being decoded into a `[]byte` field is base64-decoded, and a string that is not valid base64 produces an error rather than a garbage slice. ## Why base64 and not hex Base64 costs four output characters for every three input bytes — about 33% inflation — where hex costs two characters per byte, or 100%. Every character in the standard base64 alphabet is also a character JSON can put in a string without escaping. For a format whose job is to move opaque payloads compactly, base64 is the obvious default, and it is the same choice most JSON APIs make by hand. ## The edge cases worth memorising - **nil versus empty.** `var b []byte` is nil and marshals to `null`. `b := []byte{}` is non-nil and marshals to `""`. Round-tripping does not preserve the distinction in the direction you might hope: decoding `null` into a `[]byte` field leaves it nil, and decoding `""` gives you an empty non-nil slice. - **Arrays are not slices.** `[4]byte` and `[32]byte` are arrays. The encoder's byte-slice rule does not apply to them, so they marshal as a JSON array of numbers: `[1,2,3,4]`. This surprises people who store a `sha256.Sum256` result — which is a `[32]byte` — directly in a wire struct. Slice it (`sum[:]`) if you want the base64 string. - **Named types still count.** `type Token []byte` marshals as base64 too, because the encoder looks at the underlying type. - **`json.RawMessage` is the exception.** It is defined as a `[]byte`, but it declares `MarshalJSON`, so the encoder uses that instead of the byte-slice rule and splices the bytes in as literal JSON. - **Map values too.** A `map[string][]byte` gets base64 strings for its values by the same rule. ## Changing the representation The alphabet is fixed; there is no struct-tag option for URL-safe or unpadded base64, and none for hex. Three practical ways out: 1. Declare the field as a `string` and encode it yourself — `base64.RawURLEncoding.EncodeToString(b)` or `hex.EncodeToString(b)` — at the boundary where you build the wire struct. 2. Give the field a named type with its own `MarshalJSON`/`UnmarshalJSON`, or a text marshaler, so every use of the type agrees on the representation. 3. Keep the wire type separate from the domain type, so the domain keeps `[]byte` and only the wire struct carries the encoded string. Whichever you pick, write it down for consumers: a partner integrating against your API cannot tell from a 22-character string whether it is standard base64, URL-safe base64 or hex, and picking the wrong decoder is one of the most common integration bug reports on binary fields. ## What an interviewer is listening for That you know the rule (`[]byte` → base64 string), that you know *why* (JSON has no byte type), and that you do not confuse it with a byte array. The follow-up is usually the nil/empty distinction, because it decides whether a client sees `null` or `""` and therefore whether their own decoder blows up.