What problem does json.RawMessage solve when a JSON envelope's payload shape depends on a type field?

## The shape of the problem An event bus carries messages that all look like this: ```json {"type":"user.created","id":"9f2","payload":{"email":"[email protected]"}} ``` The outer fields are fixed; `payload` is different for every value of `type`. Go wants a concrete type per field, and `json.Unmarshal` decodes top to bottom in one pass, so a `Payload UserCreated` field is a decision you have to make *before* you have read `type`. The usual first attempt is `Payload map[string]any`. It decodes, but you have thrown the structure away: every number is now a `float64`, every nested object another `map[string]any`, and re-encoding it produces a document that is only accidentally the same as the input. Worse, for a transform that must forward the message onward, you have retyped data you never intended to interpret. ## What json.RawMessage is ```go type RawMessage []byte ``` with two methods that make it interesting to `encoding/json`: - `func (m RawMessage) MarshalJSON() ([]byte, error)` returns `m` itself — or `null` when it is nil. - `func (m *RawMessage) UnmarshalJSON(data []byte) error` copies `data` into `*m`. It is a marshaler and an unmarshaler that do as little as possible. As a struct field it means "remember the bytes of this value; do not interpret them". The decoder still validates: the input as a whole must be well-formed JSON, and the bytes you get are exactly the bytes of that one value from the input. They are copied, so the `RawMessage` outlives the input buffer safely. ## Two-stage decoding ```go type Envelope struct { Type string `json:"type"` Payload json.RawMessage `json:"payload"` } var env Envelope if err := json.Unmarshal(data, &env); err != nil { return err } switch env.Type { case "user.created": var u UserCreated if err := json.Unmarshal(env.Payload, &u); err != nil { return err } ... } ``` Stage one reads the envelope and the discriminator; stage two decodes the payload with full type safety into the struct the discriminator selected. Errors stay precise: a malformed payload fails with a message about the payload's own fields, not about the envelope. Note that `UnmarshalJSON` here is on `*RawMessage`, and it is found because `json.Unmarshal` is given `&env` — struct fields reached through a pointer are addressable, so the decoder can take the address of the field. ## Encoding: bytes straight through Because `RawMessage.MarshalJSON` returns its own bytes, assigning pre-encoded JSON to such a field splices it in as a JSON value: ```go env.Payload = json.RawMessage(`{"email":"[email protected]"}`) ``` This is the half people forget, and it is what makes `RawMessage` a *pass-through* type rather than just a lazy-decode trick. A transform step in a pipeline can decode into `map[string]json.RawMessage`, rewrite the one member it owns, and re-encode: every other member is emitted from the original bytes, so unknown fields survive, numbers keep their exact literal form, and a payload the step does not understand is forwarded unharmed. (Two details to expect: re-encoding a map sorts the member names, so field order changes; and the encoder compacts what your `RawMessage` holds, so interior whitespace from the input is dropped.) The same property makes `RawMessage` useful for a cached or precomputed fragment: encode an expensive sub-document once, keep the bytes, and slot them into many responses without re-encoding. ## Where it is the wrong answer - If you actually need to read the payload's fields in this function, decode it into a struct. `RawMessage` defers work; it does not remove it. - If the goal is "keep whatever the client sent so I can echo it back", think about whether you want to forward bytes you never validated. `RawMessage` guarantees the value is syntactically JSON and nothing more — no schema, no size bound, no check that it is an object. - A `RawMessage` in a struct that crosses a package boundary exports an obligation: every caller must know what to do with those bytes. Sometimes the honest API is an interface plus a decode function that returns a concrete type. ## Gotchas worth naming A nil `RawMessage` encodes as `null`, not as an omitted member or an empty object; if the field must disappear, use `*json.RawMessage` with `omitempty` or drop the field from the wire struct. An empty, non-nil `RawMessage` — zero bytes — is not a valid JSON value and makes the encode fail, which is the usual cause of a `json: error calling MarshalJSON for type json.RawMessage`. And a field declared `json.RawMessage` but never assigned before encoding hits exactly that case, so initialise it or make it a pointer.