8.4 encoding/json — Specification¶

The formal reference for encoding/json. Type mapping, tag grammar, error types, supported interfaces, and the Encoder/Decoder method tables. For prose explanations see junior.md, middle.md, and senior.md.

1. Top-level functions¶

2. Marshal: Go type -> JSON type¶

3. Unmarshal: JSON type -> Go target¶

4. Struct tag grammar¶

tag       ::= name ( ',' option )*
name      ::= '' | '-' | ident
option    ::= 'omitempty' | 'string'

Field visibility:

• Only exported fields participate.
• An untagged field defaults to its Go field name as the JSON key.
• An empty tag is identical to "no tag."

5. The omitempty predicate¶

Field is omitted if:

6. Field resolution for embedded structs¶

1. Build the visible-field set per depth, with depth 0 being the directly declared fields.
2. For each name, the field at the least depth wins.
3. A tie at the same depth where one field has a JSON tag and the other doesn't: tagged wins.
4. A tie at the same depth where both fields are tagged or both untagged: both are dropped silently (no error, no encoding).
5. Embedded *T (pointer to struct) is allocated on decode if needed; emits its visible fields when non-nil.
6. Tagging the embed itself (e.g., Audit \json:"audit"``) makes the embed serialize as a nested object rather than flat.

7. Supported interfaces¶

Method-set resolution follows Go's rules:

• A pointer-receiver method is in *T's method set, not T's.
• An embedded type's methods are promoted to the outer type.
• Custom marshalers on embedded types override the outer type's default struct marshaling (the embed wins; see senior.md §21).

8. Encoder methods¶

Encoder is not safe for concurrent use.

9. Decoder methods¶

Decoder is not safe for concurrent use.

Token returns one of:

10. Error types¶

All implement error. MarshalerError implements Unwrap. The others do not, so use type assertions or errors.As.

*UnmarshalFieldError and *InvalidUTF8Error exist in the package for backward compatibility but are no longer returned (deprecated).

11. json.RawMessage¶

type RawMessage []byte

func (m RawMessage) MarshalJSON() ([]byte, error)
func (m *RawMessage) UnmarshalJSON(b []byte) error

• Marshal: writes m verbatim (validated via json.Compact).
• Unmarshal: copies the raw bytes for the JSON value into *m. The bytes are owned by the decoder; copy if you need to retain them beyond the next decoder operation.

12. json.Number¶

type Number string

func (n Number) Float64() (float64, error)
func (n Number) Int64() (int64, error)
func (n Number) String() string

• Marshal: writes the literal string (must be a valid JSON number).
• Unmarshal (when Decoder.UseNumber() set): captures the JSON number's literal digits as a string.
• Without UseNumber, JSON numbers in interface{} targets become float64.

13. Object key types¶

A map key type may be:

• string (most common)
• Any integer type (encoded as decimal strings)
• Any type implementing encoding.TextMarshaler (and TextUnmarshaler for decode)

Map keys are sorted lexicographically by their JSON-encoded form on output.

14. String escaping¶

Always escaped:

• " -> \"
• \ -> \\
• Control characters U+0000..U+001F -> \u00XX
• U+2028 (LINE SEPARATOR) ->
• U+2029 (PARAGRAPH SEPARATOR) ->

Conditionally escaped (only when Encoder.SetEscapeHTML(true), which is the default):

• < -> <
• > -> >
• & -> &

Invalid UTF-8 bytes in source strings are replaced with U+FFFD (REPLACEMENT CHARACTER) in the output.

15. Concurrency guarantees¶

16. Buffer reuse and ownership¶

• Marshal returns a freshly allocated []byte. The caller owns it.
• Unmarshal reads from the provided []byte and does not retain it past the call. Strings decoded into Go strings are always new allocations.
• Decoder retains a reference to the underlying io.Reader for the lifetime of the decoder.
• RawMessage returned by Decoder.Decode aliases the decoder's internal buffer; copy if you need to retain past the next decoder operation.

17. Numeric edge cases¶

18. Top-level value types¶

A JSON document is exactly one of:

• object: {...}
• array: [...]
• string: "..."
• number: 42, -1.5, 1e10
• true, false
• null

Marshal always emits one. Unmarshal always reads one (extra trailing bytes are ignored — see professional.md §12 for the strict check).

19. Reserved patterns and special types¶

20. Version notes (Go 1.22)¶

• Cycles via pointers/slices/maps return *UnsupportedValueError (since Go 1.20, prior versions stack-overflowed).
• http.MaxBytesReader returns *http.MaxBytesError (since Go 1.19) so errors.As works.
• errors.Join (Go 1.20) is the idiomatic way to collect multiple field-validation errors.
• encoding/json/v2 is in proposal form (issue 71497, 63397) and not yet in the standard library as of Go 1.22.