Go encoding/json/v2: How to Migrate Without Breaking Your API

Go 1.27 shipped encoding/json/v2 as a stable standard library package, and if your API returns JSON, this migration can silently break clients. Four behaviors changed: invalid UTF-8 now errors instead of getting replaced, duplicate JSON keys error instead of "last one wins," nil slices/maps marshal as []/{} instead of null, and field matching is case-sensitive instead of case-insensitive. None of that shows up in a diff. It shows up in production when a mobile client that was relying on null suddenly gets an empty array and crashes on .length.

I spent an evening going through the official migration guide and the announcement post because I've got three services on encoding/json that talk to clients I don't control. Here's what actually matters if you're planning this move, not the full changelog.

What is encoding/json/v2, really?

It's a rewrite of Go's JSON package that took about six years and shipped behind GOEXPERIMENT=jsonv2 starting in Go 1.25. As of Go 1.27 (released August 19, 2026), it's in the standard library with no build flag needed, and (this is the part people miss) the old encoding/json package is now implemented on top of the v2 engine. You didn't opt into any of this just by upgrading your Go toolchain to 1.27.

The project was led by Joe Tsai, Daniel Martí, Roger Peppe, Johan Brandhorst-Satzkorn, Chris Hines, and Damien Neil. Worth noting: most of that work wasn't done by Googlers on the clock, it was community-driven, which is part of why it took so long to land. Other ecosystems go through the same slow-burn process when a core runtime default is on the table: Python's community spent years arguing over whether to keep a JIT before pulling it back out in PEP 836.

The old package stuck around for 15+ years with known flaws because breaking it would've broken half the internet's Go services. So instead of fixing encoding/json in place, the team built a new package alongside it and spent years making sure the two interoperate.

The 4 breaking changes that will bite you

These are the defaults that flip when you move to json/v2, straight from the migration guide:

The nil slice one is the sneakiest. Take this struct:

type Pet struct {
    Name      string
    Nicknames []string
}

Marshal a Pet{Name: "Remi"} with a nil Nicknames field. v1 gives you {"Name":"Remi","Nicknames":null}. v2 gives you {"Name":"Remi","Nicknames":[]}. If a frontend does data.nicknames === null ? [] : data.nicknames, that check now does nothing useful, and if it does data.nicknames.map(...) without a null guard, v1 would've thrown and v2 won't, which sounds like an improvement until you remember some client somewhere was relying on the crash to catch a bug.

Case-sensitive matching is the other one I'd watch. If your Go struct has a field tagged json:"userId" and some client sends "UserID", v1 matched it anyway. v2 won't. That's arguably the correct behavior (case-insensitive matching has always been a little insane), but "correct" doesn't help you when a partner's integration breaks at 2am.

How do you actually migrate without breaking your API?

The Go team gives you three paths, ordered roughly by how much you trust your test coverage:

1. All at once. Swap encoding/json imports for encoding/json/v2, run your test suite, ship it. Fine for internal tools or services where you control every client. I would not do this for a public API.

2. Option by option. Start from full v1 compatibility and peel off behaviors one at a time:

import (
    jsonv1 "encoding/json"
    "encoding/json/v2"
)

// Start here: identical to v1 behavior
b, err := json.Marshal(pets, jsonv1.DefaultOptionsV1())

// Then flip individual options once you've checked each one
b, err := json.Marshal(pets, jsonv1.DefaultOptionsV1(),
    json.FormatNilSliceAsNull(false))

This is the one I'd actually use. You get the new package's performance and API without eating all four behavior changes in one commit, and you can ship each option flip as its own PR with its own test.

3. jsonsplit, for anything serving real traffic. github.com/go-json-experiment/jsonsplit marshals every payload with both v1 and v2, returns the v1 result, and reports where they diverge:

jsonsplit.GlobalCodec.SetMarshalCallMode(jsonsplit.CallBothButReturnV1)
jsonsplit.GlobalCodec.AutoDetectOptions = true
jsonsplit.GlobalCodec.ReportDifference = func(d jsonsplit.Difference) {
    log.Printf("json v1/v2 mismatch: %v", d)
}

Run that in production for a week, fix whatever it flags, flip CallBothButReturnV2, watch error rates, then rip the wrapper out. This is the honest answer for anything with external clients you can't force to update. It's more setup than the other two options, but it's the only one that tells you what breaks before a client does.

Is the performance gain actually worth it?

This is where the hype runs ahead of reality, and Daniel Lemire tested it directly against Go 1.27.0. The headline "up to 10x faster unmarshal" number is real, but it's measured on unmarshaling into any (untyped maps), where v2 ran 1.5x to 2.3x faster than the old implementation in his benchmarks, and the Go team's own figures go higher depending on the shape of the data.

For typed structs, which is most real code, the story flips. Lemire found marshaling a typed struct was actually slower under v2, by about 1.5x, versus the legacy path. So "twice as fast" and "1.5x slower" are both true descriptions of the same release depending on what you're serializing. If you're mostly marshaling well-defined structs (which, be honest, most REST APIs are), don't migrate expecting a free speedup. Benchmark your actual hot path before you tell your team this upgrade pays for itself in latency. It's the same tradeoff you see any time a runtime leans toward safer defaults, like Goose betting on memory safety without a garbage collector.

Where the real win shows up is Kubernetes, which the Go team cites as seeing "orders of magnitude" improvement after switching its recursive unmarshaling from UnmarshalJSON to the new streaming-oriented UnmarshalJSONFrom interface. That's not a drop-in import swap, that's rewriting your custom marshalers to use the new interfaces — a much bigger lift, but the payoff is real if you have deeply nested custom types.

Should you migrate right now?

Honestly, no rush. The Go team has said v1 is supported indefinitely — nobody is forcing you off encoding/json, and the Hacker News discussion around the announcement makes the same point repeatedly: most commenters agreed the bigger win here is the API (streaming marshalers, options, the separate jsontext layer for pure syntax), not raw speed for typical struct-based APIs.

My take: migrate when you have a specific reason — you're hitting the MarshalJSON/streaming limitations of v1, you're building something new and want the stricter defaults from day one, or you've got a jsonsplit-shaped appetite for doing this carefully. Don't migrate because a release note said "10x faster" and you skipped the fine print. For an existing public API, budget a full sprint for the jsonsplit path if you have any external clients — the four behavior changes above are exactly the kind of thing that passes every internal test and then pages someone the first time a client sends a weird payload.

If you're deciding whether to even touch this release yet, it's worth reading how other ecosystems have handled similar "safe-by-default but technically breaking" migrations — the same caution applies whether you're swapping a JSON encoder or upgrading a major framework version.

Watch: the backstory

This is the original GopherCon talk from Joe Tsai laying out why encoding/json needed a v2 in the first place — useful context for why the defaults changed, three years before it actually shipped.

Official announcements