The Go team’s November 4 JSON API post sets out how applications can adopt encoding/json/v2, already stable in Go 1.27, without changing every call at once. Its accompanying migration guide describes a wrapper that compares implementations while returning the original output. For services with existing JSON consumers, that offers a way to discover differences before exposing them to clients.
This is migration guidance for an available API, rather than a new Go release. MrKeyoor reviewed the documentation and has not run the wrapper or measured its overhead.
A compiling import change can alter responses
The Go announcement lists defaults worth checking: v2 rejects duplicate object names and invalid UTF-8, and matches JSON names to struct fields case-sensitively. Nil slices and maps become empty arrays and objects. Existing consumers may expect different values, so a successful build alone cannot settle compatibility.
The original encoding/json package remains supported indefinitely under Go’s compatibility promise, according to the post. Teams can therefore evaluate the new API without treating migration as a support deadline.
Compare results before returning them
The migration guide describes jsonsplit, a wrapper whose CallBothButReturnV1 mode compares both implementations while retaining v1 output. It can report differences and optionally identify which compatibility options explain them.
That comparison has an explicit cost. Running both approximately doubles marshaling work, and automatic option detection adds more. The guide provides sampling to limit how often the comparison runs. It also describes starting with DefaultOptionsV1 and changing individual behaviours gradually.
For a service team, the next useful result is a record of differences on its own payloads. Check whether consumers depend on each difference before changing the response they receive. The guide’s staged approach makes that investigation possible; it cannot establish compatibility for an application that has not collected the evidence.