Go 1.27 encoding/json v2: What Breaks Before August

Go 1.27 RC1 shipped on June 18, and developers quickly latched onto the headline: generic methods are finally here. That’s covered. What’s not getting enough attention is the other change in this release—the one that will actually break production code. encoding/json/v2 has officially entered the standard library, bringing four default behavioral changes that Go developers have relied on, incorrectly, for fifteen years. GA ships in August. You have a few weeks to find out what breaks before it ships to production.

The Broken JSON Package Is Getting Fixed—and That Means Your Code Might Break

The original encoding/json was written in 2009. It was useful, but it accumulated design debt that the community has complained about ever since: case-insensitive field matching, silent acceptance of invalid UTF-8, no way to reject duplicate keys, and no streaming support worth using. The Go team spent three years running go-json-experiment as an external package before it was ready for the standard library. In Go 1.27, it graduates. The import path is encoding/json/v2, and it ships with stricter defaults that reflect what JSON handling should have looked like from the start. Read the Go 1.27 release notes for the full list.

Here’s the important nuance: even if you never import encoding/json/v2, your code is affected. Starting in 1.27, the original encoding/json is internally backed by v2’s implementation. Some behavior changes silently. Test your JSON handling against RC1 now—GOEXPERIMENT=jsonv2 go test ./...—before August forces the issue.

Case-Sensitive Field Matching: The encoding/json v2 Change That Will Find You

This is the one that will hit the most codebases. In v1, unmarshaling {"USER_ID":"abc"} into a struct with json:"user_id" worked fine. The parser normalized case silently. Convenient. Also a bug—one that appeared in CVE-2020-16250 and related authorization bypasses where attackers used casing tricks to confuse parsers. According to Trail of Bits’ security audit of Go parsers, case-insensitive struct binding represents a documented attack surface. In v2, field names must match exactly. If your struct tag says json:"user_id", the JSON must send user_id. Send USER_ID and the field silently stays at its zero value. No error.

// v1 — all three work (incorrectly)
json.Unmarshal([]byte(`{"USER_ID":"abc"}`), &req)   // ✓ v1 allows it
json.Unmarshal([]byte(`{"User_Id":"abc"}`), &req)   // ✓ v1 allows it too

// v2 — only exact match works
jsonv2.Unmarshal([]byte(`{"user_id":"abc"}`), &req)   // ✓
jsonv2.Unmarshal([]byte(`{"USER_ID":"abc"}`), &req)   // silent zero value

// Preserve v1 behavior during migration:
jsonv2.Unmarshal(data, &req, jsonv2.MatchCaseInsensitiveNames(true))

The fix is straightforward: audit your struct tags, ensure they match exactly what your clients send, and enforce casing consistency on both sides. If you’re working with external APIs or user-controlled JSON and cannot guarantee casing, use MatchCaseInsensitiveNames(true) to preserve v1 behavior during migration. Don’t inherit the new default without testing first.

Nil Slices and Maps Now Serialize as Empty, Not Null

The second behavioral shift is subtler but breaks REST API contracts. In v1, a nil slice serializes to null. In v2, it serializes to []. Same for nil maps: v1 gives null, v2 gives {}. If any downstream client distinguishes between “field absent or null” and “field explicitly empty,” your API response now means something different without any code change on your end.

type Response struct {
    Tags []string `json:"tags"`
}

resp := Response{Tags: nil}

// v1 output: {"tags":null}
// v2 output: {"tags":[]}

// Preserve v1 behavior:
jsonv2.Marshal(&resp, jsonv2.FormatNilSliceAsNull(true))

Both v2 defaults are arguably more correct—[] and {} are the honest representations of an empty collection. However, “more correct” doesn’t help you if clients were written against v1 semantics. Check your API contracts before August.

Related: Go 1.27 RC1: Generic Methods Land — Here’s What Changes Now

Drop google/uuid From Your go.mod

On a more positive note, Go 1.27 finally adds a native uuid package to the standard library. The google/uuid package has been Go’s mandatory first import for database services since the language’s early days. That dependency is now gone. The new stdlib uuid package supports New() (v4 by default), NewV4(), NewV7(), Parse(), and MustParse(). The type is [16]byte—identical to google/uuid—so migration is a single import path change with no type casting required.

// Before Go 1.27
import "github.com/google/uuid"
id := uuid.New()      // v4

// Go 1.27 stdlib
import "uuid"
id := uuid.New()      // v4
idV7 := uuid.NewV7()  // v7 — time-ordered, better for DB primary keys

The inclusion of NewV7() is worth noting. UUIDv7 is time-ordered: the first 48 bits encode a Unix timestamp in milliseconds. In B-tree database indexes—PostgreSQL, MySQL—random v4 UUIDs fragment pages on insertion. V7 UUIDs insert sequentially, which matters for write-heavy tables. If you’re using UUIDs as primary keys, switch to v7.

Performance: Up to 10x Faster Unmarshal

v2 marshaling is at parity with v1. Unmarshaling, however, is significantly faster—up to 10x—when you implement the new streaming interfaces. The old MarshalJSON() ([]byte, error) interface allocates an intermediate byte slice. The new MarshalJSONTo(*jsontext.Encoder) error writes directly to the encoder with no intermediate allocation. Kubernetes kube-openapi saw “orders of magnitude” improvement switching from UnmarshalJSON to UnmarshalJSONFrom. You won’t get those gains just by changing import paths—you need to implement the new interfaces where performance matters. The detailed v1 vs v2 comparison at antonz.org walks through the benchmarks.

Key Takeaways

• Run GOEXPERIMENT=jsonv2 go test ./... against your services now—RC1 is out, GA is August 2026.
• Audit struct tags and client-side JSON field casing. Case-insensitive matching is gone by default. Silent zero values, no errors.
• Check API responses where nil slices or maps appear—v2 serializes them as [] and {} instead of null.
• Remove github.com/google/uuid from go.mod—the stdlib uuid package is a drop-in replacement. Use NewV7() for database primary keys.
• For real performance gains, implement MarshalerTo and UnmarshalerFrom—the new streaming interfaces are where the 10x speedup lives.

The v2 defaults are right. Case-insensitive JSON parsing was a bad idea in 2009 and it’s still a bad idea. Silent duplicate keys have caused real security vulnerabilities. V2 fixes these. The migration burden falls on code that was arguably relying on bugs. Use the opt-in compatibility flags where you need them, but treat this as a forcing function to clean up your JSON handling before it becomes someone else’s CVE.