Go 1.27 adds json/v2 with up to 10x faster unmarshal

A Go service that parses a lot of JSON can now read it up to ten times faster. The API does not change. Go 1.27 added two new standard library packages today. They are encoding/json/v2 and encoding/json/jsontext. Seven Go team members wrote the announcement, led by Michael Pratt and Joe Tsai.

The post says unmarshal in v2 is up to ten times faster than in v1. Marshal is at parity, the Go team says. It is "sometimes faster, sometimes slower". The largest speedups come from two new interfaces, MarshalerTo and UnmarshalerFrom. They stream through a jsontext encoder or decoder. They do not build an intermediate representation.

What v2 changes on the wire

Several default behaviours are stricter in v2. Invalid UTF-8 now returns an error. The Go Blog calls this RFC 8259 compliance. Duplicate JSON object member names are rejected. Field name matching on unmarshal is case sensitive. In v1 it was case insensitive. A nil slice or nil map is marshalled as an empty JSON array or object. In v1 it was null.

The omitempty struct tag now behaves differently too. In v1 it only dropped a literal empty string. In v2 it drops any empty JSON value. That covers null, the empty string, the empty array and the empty object. time.Duration no longer has a default encoding, and the caller must pick one.

How a team moves from v1 to v2

The old encoding/json stays in the standard library. The Go team says v1 now calls v2 inside the library. Existing code keeps working. A package can mix v1 and v2. A team can migrate one file at a time. Each strict default has a per-call option that restores the old behaviour.

The v2 API also takes options on Marshal and Unmarshal. Those options pass through custom marshaler and unmarshaler methods. In v1, options could not be passed in at all.

What this changes for Go services

A Go service parses requests and reads JSON from queues and files. The standard library's JSON code uses real CPU on that work. A ten times speedup on unmarshal lands directly on that line of the budget. The API does not change. A service that produces more than it reads will see less. Marshal is at parity.

The wire changes need checking before v2 reaches a public API. Some consumers rely on v1 accepting invalid UTF-8. Some rely on it accepting duplicate keys. Some rely on loose field name matching. Some read null back as nil. All of them will see a different shape in v2. The options system keeps the old shape at the specific call sites that need it. The hot path can still move to the faster default.

Source

What's new in Go 1.27's encoding/json/v2, The Go Blog.