encoding/json/v2 Migration Guide - The Go Programming Language

Common problems companies solve with Go
Stories about how and why companies use Go
How Go can help keep you secure by default
The official Go language specification
A complete introduction to building software with Go
Reference documentation for Go's standard library
Learn what's new in each Go release
Tips for writing clear, performant, and idiomatic Go code
Videos from prior events
Meet other local Go developers
Learn and network with Go developers from around the world
The Go project's official blog.
Get help and stay informed from Go
Introduced in Go 1.27, the encoding/json/v2 package is a major revision of the original encoding/json package. This guide describes why you may want to migrate from the v1 to v2 package, and the mechanics of doing so safely.
First things first: you don’t have to! The encoding/json package will never go away. It is covered by the Go 1 compatibility promise, so packages using encoding/json will continue working indefinitely.
In addition, encoding/json and encoding/json/v2 are compatible with each other. For example, if a type implements custom marshaling behavior with encoding/json/v2.MarshalerTo, the callers marshaling this type through encoding/json.Marshal will still go through the custom marshaler. Similarly, new json struct tags introduced in Go 1.27 alongside encoding/json/v2 are also supported by encoding/json.
Though you are not required to migrate, there are several good reasons to do so:
First, the new API is easier to use. For example, easily marshal to an io.Writer with encoding/json/v2.MarshalWrite, rather than needing an encoding/json.Encoder. encoding/json/v2.Marshalers allows overriding the marshal behavior of specific types, even if you do not control those types. encoding/json/v2.MatchCaseInsenstiveNames allows control over the case sensitivity of matching JSON object member names to Go struct fields.
While these improvements are nice, the best reason to migrate is that the v2 package chooses stricter, more interoperable defaults than v1. The encoding/json documentation contains the complete set of differences, but some highlights include:
These changes are designed to make encoding/json/v2 more interoperable with the wider JSON ecosystem, less surprising, and less error-prone. But they are not backwards compatible; some applications may depend on the v1 behavior. Therefore, migration to v2 must involve careful testing to ensure compatibility.
For simple marshaling and unmarshaling, the Go APIs are largely compatible at the language level, and thus the API migration is trivial. For example, b, err := json.Marshal(v) will continue to compile simply by switching import "encoding/json" to import "encoding/json/v2".
The difficult part of migrating from v1 to v2 is not the API differences, but behavior changes in marshaling and unmarshaling. Consider this program:
When run, this outputs:
If we trivially migrate this program to encoding/json/v2 by changing the import, the program still compiles. When run, it outputs:
Notice that the “Nicknames” field for Remi has changed from null to []. If this were a new program, using an empty array is likely a nice improvement, but in an existing application downstream consumers of this output may be depending on the presence of null, so this change may break them.
All of the places where v2 behavior diverges from v1 are covered by Options which allow specifying the v1 behavior using the v2 API. To use the v2 API, but specify all v1 behaviors, use DefaultOptionsV1:
When run, this once again outputs null:
The DefaultOptionsV1 documentation lists the full set of options used for v1 compatibility. Later options override earlier options, so you can use this list to enable v2 behaviors one at a time.
Depending on the type of application and its risk tolerance, there are several different ways to approach a v2 migration:
If the application is simple or has high risk tolerance (there is little consequence to the migration causing problems), then there may be no need for an elaborate migration process. Simply update callsites to use encoding/json/v2, make sure the tests pass, and check it in.
If you do run into compatibility issues, the source of the difference may be clear from the change or error message, in which case you can set the appropriate compatibility option. If the source of the problem is not clear, you may want to use one of the approaches below to help troubleshoot.
This can also be a quick way to find and fix obvious issues (such as those identified by unit tests) before moving on to a more nuanced approach to track down the remainder.
If the application is complex or has a low risk tolerance, then you may need to take a slower, more careful approach.
As mentioned above, calling Marshal or Unmarshal with DefaultOptionsV1 makes the call behave identically to encoding/json. As a first step, migrate all calls to encoding/json/v2 with DefaultOptionsV1. This is a trivial and safe change; in fact, this is exactly how encoding/json implements Marshal and Unmarshal!
Additional passed options override earlier options, so you can disable individual v1 compatibility options. For example, json.Marshal(v, jsonv1.DefaultOptionsV1(), json.FormatNilSliceAsNull(false)) will behave like v1 except that nil slices format as empty arrays.
This provides a path to perform a slower migration rather than changing all behavior at once. You could enable one option at a time to be very sure what is changing, or group similar options. Alternatively, when troubleshooting these options provide a way to bisect down to the exact breaking behavior change, similar to the option detection we’ll see in jsonsplit below.
github.com/go-json-experiment/jsonsplit is a JSON wrapper package that aids migration by reporting differences between v1 and v2 in a production setting.
jsonsplit provides Marshal and Unmarshal wrapper functions which behave the same as encoding/json by default, but can be configured at runtime to use v1, v2, or both.
W