Go's json/v2 Turns Nil Slices Into [] and Rejects Duplicate Keys, and Go 1.27 Already Runs on It
Software / explainer
Go's json/v2 Turns Nil Slices Into [] and Rejects Duplicate Keys, and Go 1.27 Already Runs on It
The Go team's Nov. 4 post declares encoding/json/v2 stable, and the migration guide shows which of your payloads change when you switch the import.

The Go team declared encoding/json/v2 and encoding/json/jsontext "stable and generally available in Go 1.27" in a blog post on Nov. 4. Go 1.27.0 shipped on Aug. 19, so the code has been in toolchains for 11 weeks. Deadlines that arrive as defaults, the way Chrome's XSLT removal on Nov. 17 did, are the ones teams miss. This migration has no deadline at all, which is its own risk.
The post is signed by seven authors, among them Michael Pratt, Joe Tsai and Daniel Martí. Martí drafted the first v2 design in late 2020, and the authors count about six years from that draft to stable.
What changes in the bytes your service emits
Most of the migration is not API. It is a short list of defaults, and each one can change a payload that a client already parses. The migration guide lists them side by side.
| Behaviour | v1 (encoding/json) | v2 (encoding/json/v2) |
|---|---|---|
| Invalid UTF-8 in a string | Replaced with U+FFFD | Error |
| Duplicate object member name | Accepted | Error |
| Nil slice or map | null | [] or {} |
| Bad struct tag types | Never reported | Runtime error |
| Field name matching | Case-insensitive | Case-sensitive |
The nil slice row is the one to read twice. A handler that returns a struct with an unset Nicknames slice sends null today. Under v2 it sends []. A hypothetical TypeScript client that checks if (user.nicknames === null) stops taking that branch, and nothing in the Go build tells you.
The case-sensitive row bites the other direction, and it is the same kind of break that Ubuntu 26.04 users hit with sudo-rs, where scripts leaned on behaviour the rewrite dropped. A request body with "UserID" used to fill a field tagged userid; under v2 it silently does not. The post also lists time.Duration, which v2 refuses to serialise at all because it has no default representation.
Go 1.27 already swapped the engine under v1
The Go 1.27 release notes say encoding/json is "now backed by the v2 implementation" and that behaviour is preserved, though "the exact text of error messages may differ". If a test compares an error string from json.Unmarshal, that is the first thing to fail after the toolchain bump.
The notes also give an escape hatch: build with GOEXPERIMENT=nojsonv2 to restore the original v1 implementation. The migration guide, by contrast, says there is no runtime flag for v2 itself. The choice there is the import path plus options.
Three ways to move, by risk appetite
The guide describes three strategies, and the middle one is the one most services will pick.
- Switch the import to
encoding/json/v2and fix what breaks. The guide's example shows a nilNicknamesslice flipping fromnullto[]with no compile error. - Move every call to v2 but pass
DefaultOptionsV1(), which reproduces v1 behaviour, then drop the compatibility options one at a time, for examplejson.FormatNilSliceAsNull(false). - Run both side by side in production with
jsonsplit.
jsonsplit lives under the go-json-experiment GitHub organisation, carries a BSD-3-Clause licence and, when checked on Nov. 5, had 3 stars and 15 commits. The guide says its CallBothButReturnV1 mode returns v1 output while reporting differences, and that checking both versions roughly doubles marshal cost. SetMarshalCallRatio samples a fraction of calls to limit that.

What the speed claim covers
The Go 1.27 notes say marshal performance is "broadly at parity" with the old implementation and unmarshal is "significantly faster". The blog post puts a number on it: up to a 10x improvement in unmarshal benchmarks. Neither page names the benchmark inputs or the hardware, so 10x is the ceiling the Go team chose to quote, not a number to plan capacity around.
The larger gain comes from opting in to the new streaming interfaces. The post says switching one Kubernetes type from UnmarshalJSON to UnmarshalJSONFrom in kube-openapi improved performance "by orders of magnitude". The kube-openapi pull request list shows two merged changes from contributor Jefftree: #604 bumped the go-json-experiment dependency on May 9, and #649 removed a redundant reflection step on Oct. 1. Neither page carries benchmark numbers, so the "orders of magnitude" figure rests on the Go team's word alone.
The v1 package is not going anywhere. The post says it stays supported indefinitely under the Go 1 compatibility promise, and more unmarshal optimisations are planned for Go 1.28. The release page lists go1.27.3, issued Oct. 19 with crypto/x509 security fixes, as the latest point release.
Sources
More in Software
- 01Psalm 7 Turns On Taint Analysis by Default for PHPThe static analyzer's new major release adds a prompt-injection taint kind, replaces its purity annotations with capabilities, and has already reached 7.2.0 within a week.
- 02Node.js 27 Alpha Doubles the Default Heap on 8 GB MachinesThe first release under Node's annual schedule also changes the V8 serialization format, so a payload written by 27 cannot be read by 26.
- 03Meta's Astryx Design System Hits 19.7k Stars, Still in BetaThe MIT-licensed React 19 library claims 150+ components and 13,000 internal apps, but its charts and Vega packages exist only under a canary tag.
- 04KetchUp, the Rust SketchUp Alternative, Is Now BenchUpThe MIT-licensed woodworking modeler imports .skp files and runs in a browser on WebGPU, and its README spells out which old project files survive the rename.