Programming Languages / ARTICLE

Go 1.27 Stabilizes encoding/json/v2 and jsontext Packages

Go 1.27 stabilizes encoding/json/v2 and encoding/json/jsontext, addressing long-standing JSON behavior flaws and adding streaming interfaces with significant unmarshal speedups.

Problems with encoding/json

encoding/json has been part of the Go standard library since before Go 1.0, but it carries behavior flaws that the Go 1 compatibility promise makes difficult to fix directly. The package accepts invalid UTF-8 even though RFC 8259 requires valid UTF-8. It also accepts JSON objects with duplicate member names; RFC 8259 gives no guidance on duplicates, and this ambiguity has been exploited in security contexts, including CVE-2017-12635. Nil slices and maps marshal to null, which many JSON implementations reject when expecting an array or object. A survey showed most Go users prefer empty arrays and objects. Unmarshaling matches JSON member names to Go struct fields case-insensitively, a surprising default that creates security and performance issues. Pointer-receiver MarshalJSON methods are called inconsistently, a bug that cannot be fixed without breaking existing applications.

The API also limits usability. json.NewDecoder(r).Decode(v) fails to reject trailing data after the JSON value. Options set on Encoder and Decoder types do not apply to Marshal and Unmarshal functions, and custom Marshaler or Unmarshaler implementations cannot receive those options. Compact, Indent, and HTMLEscape write only to a bytes.Buffer. MarshalJSON must allocate a []byte and requires encoding/json to validate and reformat output. UnmarshalJSON needs a complete JSON value, forcing encoding/json to parse boundaries before the method parses again. Encoder and Decoder buffer entire JSON values, and recursive Marshal or Unmarshal calls can become quadratic.

jsontext and the v2 API

Go 1.27 marks encoding/json/v2 and encoding/json/jsontext as stable. jsontext handles JSON syntax without reflection, providing Encoder, Decoder, Value, and Token types. Value is a named []byte identical to the old RawMessage, which is now a type alias. Token represents arbitrary JSON tokens without allocation. The new MarshalJSONTo and UnmarshalJSONFrom interfaces accept a *jsontext.Encoder or *jsontext.Decoder, letting types process JSON as a stream instead of returning or receiving complete values.

The v2 package keeps Marshal and Unmarshal with similar signatures but adds options as a first-class argument. MarshalWrite, UnmarshalRead, MarshalEncode, and UnmarshalDecode operate directly on io.Writer, io.Reader, or jsontext types. Caller-specified customization allows overriding marshaling for arbitrary types through WithMarshalers and WithUnmarshalers.

Behavior changes and performance

v2 changes several defaults: invalid UTF-8 and duplicate object names now return errors; nil slices and maps marshal to empty arrays and objects; unmarshaling uses case-sensitive field matching; omitempty omits fields that encode as null, “”, [], or {}; and time.Duration returns an error because it has no default representation. Most changes can be reverted to v1 semantics with tags or options.

Marshal performance in v2 is roughly at parity with v1, sometimes slightly faster or slower. Unmarshal benchmarks show improvements up to 10x. Types that migrate from Marshaler and Unmarshaler to MarshalerTo and UnmarshalerFrom benefit from streaming; Kubernetes reported that switching recursive OpenAPI parsing from UnmarshalJSON to UnmarshalJSONFrom improved performance by orders of magnitude.

v1 remains supported indefinitely. Under the hood, v1 is implemented in terms of v2 using compatibility options, so packages using v1 and v2 can work together. A v1 package can call a type’s v2 MarshalJSONTo method, and a v2 package can call a type’s v1 MarshalJSON method. This design also allows gradual migration of call sites.

END
Feedback