Go jsonv2 Explained: What Changes When You Switch From encoding/json

CodexFuse Team · 2026-11-06T03:37:31.362Z · 19 min read min read

Go jsonv2 Explained: What Changes When You Switch From encoding/json

Go jsonv2 is the new JSON API that shipped with Go 1.27 on August 19, 2026, and it is the first major revision of Go's JSON handling. The November 4 blog post is the announcement, not the launch: the code had already been stable for 77 days when the post went up, and the post itself is only two days old as of this writing. If you write Go services that read or write JSON, this guide explains what changes, what stays the same, and how to decide whether to switch.

Before you touch a single import, fingerprint a sample of your current JSON output with a SHA-256 hash generator, so you can prove later that only the intended fields changed. Most Go services in production run on VPS hosting, and a JSON change that slips through testing shows up there first, in front of real clients. This guide walks through the five breaking defaults, the new API, the performance picture, and a migration path you can run one option at a time.

What Is Go jsonv2?

Go jsonv2 is the pair of packages encoding/json/v2 and encoding/json/jsontext, stable and generally available in Go 1.27. The first package is the semantic layer: it marshals Go values into JSON and unmarshals JSON back into Go values. The second is the syntactic layer underneath it: it encodes and decodes raw JSON text as tokens and values, with true streaming and no reflection.

Three packages now share the JSON job, and the table below maps them. The old encoding/json package is still there, and it still works exactly as before. Under the hood it now runs on the v2 engine, with a set of compatibility options switched on, so existing code gets faster unmarshaling without changing behavior.

The work behind jsonv2 took about six years, from a draft idea in late 2020 through a public discussion in late 2023, a formal proposal in early 2025, and a run as a Go experiment in Go 1.25. That long runway matters: the design was tested against real codebases, including the Go protobuf module's JSON logic, before it became stable.

What Changes When You Switch From encoding/json to encoding/json/v2?

The switch is small at the source level and large at the behavior level. Changing the import is usually enough to make your code compile, because the function names are the same. These go jsonv2 breaking changes are what actually alter your program's output, and the table below is the whole story in one place.

Two facts keep this table from being scary. First, every change has an option that restores the old behavior, so you can migrate one behavior at a time. Second, the old package is not going anywhere: the migration guide states that encoding/json will never go away, because the Go 1 compatibility promise covers it.

Why Did Go Build a New JSON API?

The original package had three kinds of problems, and the Go team names all three in the announcement. Some behaviors were surprising or unsafe, like case-insensitive matching that could silently fill the wrong field.

Some API gaps had no clean fix, like the lack of a way to reject unknown members that survived a custom unmarshaler. And some performance limits were structural, like custom marshal methods that forced the package to allocate, re-validate, and re-parse.

The performance limits are worth understanding, because they explain the new design. In v1, a MarshalJSON method returns bytes, so the package must allocate for the result and then re-validate and re-format it.

An UnmarshalJSON method receives bytes too, so the input gets parsed twice: once to find the value, once inside the method. Recursive calls inside custom methods could even turn quadratic. The v2 answer is streaming: MarshalJSONTo writes tokens straight to the encoder, and UnmarshalJSONFrom reads tokens straight from the decoder, so nothing is buffered, re-validated, or parsed twice.

There is also a security thread running through the changes. Duplicate object names had been exploited before, in CVE-2017-12635, and invalid UTF-8 handling that silently substitutes a replacement character can hide corrupt input. The v2 defaults treat both as errors, which is the stricter and more interoperable reading of RFC 8259, the JSON specification.

Does Case-Sensitive Matching Break Existing Structs?

In v1, a JSON member named userID would fill a struct field tagged json:"userId", because matching ignored case. In v2, the match is exact, so that field stays at its zero value, and no error is raised. The failure is silent, which makes it the most dangerous of the five changes for existing APIs.

The Go team calls case-insensitive matching a surprising default, a potential security vulnerability, and a performance limitation. Two different fields that differ only by case could collide, and the matching itself cost work on every unmarshal.

If your clients send mixed-case member names, test with real payloads before switching. The escape routes are the MatchCaseInsensitiveNames option for a whole call, or the case:ignore tag on a single field, which also ignores dashes and underscores.

A related trap: v2 reports a runtime error for structurally invalid Go types, such as a malformed struct tag. In v1, that tag was silently ignored. If you apply the string tag option to a type that cannot be stringified, v1 ignores it and v2 errors, so the fix is to drop the tag, not to suppress the error.

Why Are Duplicate Keys an Error Now?

In v1, the JSON object {"a":1,"a":2} was accepted, and the last value won. In v2, the same input is an error, unless you pass jsontext.AllowDuplicateNames(true). The reason is ambiguity: two values for one name mean the sender and the receiver can disagree about which one counts, and attackers have exploited exactly that disagreement before.

For most APIs this change is invisible, because well-behaved clients never send duplicate names. It bites in two places: hand-built test fixtures that repeat a key by accident, and log pipelines that merge JSON objects by concatenation.

Both are worth a grep before you migrate. The JSON formatter on CodexFuse can help you spot a repeated key in a sample payload before you run it through v2.

Why Does Invalid UTF-8 Fail Instead of Being Replaced?

JSON text must be valid UTF-8; RFC 8259 requires it. In v1, bytes of invalid UTF-8 inside a string were silently replaced with the Unicode replacement character, U+FFFD, and the program carried on with corrupted data. In v2, the same input is an error, unless you pass jsontext.AllowInvalidUTF8(true).

Silent replacement is the kind of behavior that looks helpful and causes real damage. A corrupted name, a mangled address, or a broken token can travel through three services before anyone notices the original bytes are gone.

The v2 default fails fast at the boundary, where the bad bytes can still be traced to their source. If you ingest data from systems you do not control, expect this error to appear, and decide up front whether to reject the payload or to opt back into replacement.

Why Does a Nil Slice Become [] Instead of null?

In v1, a nil Go slice or map marshals as the JSON value null. In v2, a nil slice marshals as an empty array [] and a nil map as an empty object {}.

The Go team ran a survey before choosing this default, and most Go users said they preferred the empty form. JavaScript clients usually agree: an empty array is easier to map over than a null that needs a special case.

The change is silent, and it breaks a specific contract. A front end that checks === null to mean "not loaded yet" will now see an empty array and render an empty list instead of a loading state. The migration guide's own worked example shows the difference on a two-record sample, adapted here with a project tracker instead of pets.

Only one of the two records changes, but that is the point: the difference is easy to miss in a large response, and it is a behavior change, not a formatting one. If your clients distinguish null from empty, restore the old output with FormatNilSliceAsNull and FormatNilMapAsNull, and migrate the clients first. A JSON validator can confirm that both outputs are valid JSON, so the question is never validity, only meaning.

What Does omitempty Mean in jsonv2?

This is the change that trips up even careful readers, so it gets its own section. In v1, omitempty omits a field when the Go value is empty: false, 0, a nil pointer, a nil interface, or an empty array, slice, map, or string. In v2, omitempty omits a field when the JSON value is empty: a JSON null, an empty string, an empty object, or an empty array.

For arrays, slices, maps, and strings, the two definitions agree, so most existing tags behave identically. The difference lands on bools, numbers, pointers, and interfaces.

A score of 0 or a flag set to false is a Go-empty value, so v1 omits it, but it encodes as the JSON number 0 or the JSON boolean false, which are not empty JSON values, so v2 keeps it. If you relied on the old behavior, the migration is to switch those fields to the new omitzero tag, which omits a field when it holds its zero Go value.

And to correct a common misunderstanding: omitzero is a new opt-in tag, not a changed default. It is supported identically in v1 and v2, and it exists precisely so that bool, number, pointer, and interface fields can keep the old omitempty behavior under the new definition. It also respects an IsZero method when the type defines one, which makes it useful for types with a well-defined zero value, such as netip.Addr and time.Time.

What Else Changes? The Rest of the Differences

The blog lists six behavior changes, and the go 1.27 json v2 package documentation carries the complete list of 15 differences between the two versions. The json v2 vs v1 go comparison below covers the remaining differences most likely to affect a real codebase, with the option that restores the old behavior in each row.

Two rows deserve a second look. Map ordering is non-deterministic in v2, so golden files and snapshot tests that compare raw JSON text will fail even when the data is identical; sort the keys or compare parsed values instead. And the string tag restriction means a struct tag that used to quote a string will now error, which is the same class of strictness as the malformed-tag error: the fix is to correct the tag, not to hide the error.

Unknown members deserve a note of their own, because the default did not change: both versions ignore them. What changed is the quality of the opt-in.

In v1, Decoder.DisallowUnknownFields lost its effect inside a custom UnmarshalJSON method, because options did not flow down the call stack. In v2, RejectUnknownMembers is an option passed to the call, so it applies uniformly, including inside custom unmarshalers.

How Fast Is jsonv2, Really?

The Go team's numbers are clear, and they are the Go team's numbers. Marshal performance is roughly at parity with v1: sometimes slightly faster, sometimes slightly slower.

Unmarshal performance is significantly faster, with benchmarks demonstrating improvements of up to 10x. That up to 10x figure is the Go team's benchmark claim, not a CodexFuse measurement, and it is workload-dependent: a payload that took 10 seconds to unmarshal would take about 1 second at the fast end of the range, but most payloads will see a smaller gain.

The reason unmarshal is faster is the streaming design from the earlier section. Custom unmarshal methods in v2 read tokens as they arrive, instead of receiving a fully parsed byte slice and parsing it again.

The Go team points to a Kubernetes service that parsed OpenAPI specifications inside UnmarshalJSON methods: switching to the streaming UnmarshalJSONFrom interface improved its performance by orders of magnitude. The blog also says to expect additional improvements in Go 1.28, though no date for that release has been verified.

One more performance note, because it surprises people: switching to v2 does not speed up your marshaling. If your service is marshal-bound, the new API will not move the needle, and the honest reason to migrate is the stricter defaults and the cleaner API, not speed. If your service is unmarshal-bound, the upgrade alone, without changing any imports, already helps, because v1 now runs on the v2 engine.

Should You Migrate to jsonv2, or Stay on encoding/json?

The migration guide opens its answer with three words: you don't have to. The old package is covered by the Go 1 compatibility promise, it will stay supported indefinitely, and it now runs on the v2 engine, so upgrading the toolchain already buys you the faster unmarshal. If your API is stable, your clients depend on null for nil slices, and nothing in v2 tempts you, staying is a reasonable engineering decision.

Migrate when the stricter defaults are what you want. If you are building a new service, the docs say all new usages of JSON in Go should use the v2 package.

If your API takes JSON from untrusted clients, rejecting duplicates and invalid UTF-8 at the boundary is a real security improvement. And if you maintain custom marshalers, the streaming interfaces and the per-call options remove workarounds you may have lived with for years.

The three strategies are not rivals; they are steps on one road. A team can start with the gradual path in development, use jsonsplit to watch production traffic, and finish with a full switch once the difference log is empty. The cost of the production-watching step is real but bounded: running both implementations approximately doubles the cost of marshaling, and the tool lets you sample a fraction of calls to keep that cost down.

How Do I Migrate to Go jsonv2 in Five Steps?

Every go json v2 migration starts the same way, whether the codebase is one service or fifty. The five steps below follow the official guide's order, and each one is safe to stop at: nothing here commits you to finishing.

1. Upgrade to Go 1.27 and run your tests. The old package now runs on the v2 engine, so the first failures you see are tests that compare error strings, which may have changed wording.
2. Fingerprint your JSON output before and after. Hash a sample of real responses, and use a JSON to CSV converter to flatten a sample response into rows for a side-by-side diff, then keep the before-copy until the migration is done.
3. Switch one call site to encoding/json/v2 and compare. Start with an internal endpoint, not a public API, and read the diff before you widen the change.
4. Adopt the v2 behaviors one option at a time. Begin with DefaultOptionsV1, which reproduces v1 exactly, then disable one compatibility option per commit until the options list is empty.
5. Watch production with jsonsplit before you commit. Run both implementations on live traffic, return the v1 result, and fix every difference the log reports before switching the return value to v2.

The gradual step looks like this in code. The v2 Marshal call below starts from the full v1 behavior set, then switches a single behavior, nil slices, to the v2 form.

import "encoding/json/v2"
import jsonv1 "encoding/json"

// Behaves exactly like v1, except nil slices encode as [].
b, err := json.Marshal(v, jsonv1.DefaultOptionsV1(), json.FormatNilSliceAsNull(false))

Two escape hatches exist, and neither is a plan. Building with GOEXPERIMENT=nojsonv2 restores the original v1 implementation, but the release notes say that opt-out is expected to be removed in a future release, so it buys time, not a future. And if the new implementation breaks you in a way the guide does not cover, the Go team asks you to file an issue rather than work around it silently.

One last scope note: CodexFuse does not offer a Go jsonv2 tool. The JSON tools linked in this guide format, validate, and convert payloads, which is the part of the job a web tool can do; the migration itself happens in your Go code.

Sources

• Go blog, "A new Go API for JSON" (go.dev/blog/jsonv2, November 4, 2026) — the announcement post; the five behavior changes, the performance claims, the history, and the migration overview.
• Go documentation, "encoding/json/v2 Migration Guide" (go.dev/doc/jsonv2-migration) — the Pet/Nicknames worked example, the DefaultOptionsV1 gradual path, the three migration strategies, and the jsonsplit production procedure.
• Go 1.27 release notes (go.dev/doc/go1.27) — jsonv2 stable in Go 1.27, v1 backed by the v2 engine, the GOEXPERIMENT=nojsonv2 opt-out, and the performance summary.
• Go blog, "Go 1.27 is released" (go.dev/blog/go1.27, August 19, 2026) — the ship date and the v2 summary.
• Package documentation, encoding/json/v2 (pkg.go.dev/encoding/json/v2) — the tag options, including omitzero and the redefined omitempty, and the security considerations.
• Package documentation, encoding/json, "Migrating to v2" (pkg.go.dev/encoding/json) — the complete list of 15 differences between v1 and v2.
• endoflife.date, Go release history — cross-check for the August 19, 2026 Go 1.27 ship date.
• versionlog.com, Go changelog — cross-check for the August 19, 2026 Go 1.27 ship date.
• ImportStatic, "Go JSON v2 Migration: What Breaks in Go 1.27" (importstatic.com) — seen in search results on November 6, 2026; the upgrade-first, test-error-strings migration framing.
• CoderCops, "Go encoding/json v2 Migration: What Changes in Your Code" (blog.codercops.com) — seen in search results on November 6, 2026; the five differences and the per-call-site migration framing.
• C# Corner, "Go 1.27 encoding/json/v2: Testing Compatibility Before Moving Existing Go APIs" (c-sharpcorner.com) — seen in search results on November 6, 2026; the compatibility-testing framing.
• Medium, "Go 1.27's encoding/json/v2: A Complete Rewrite of JSON Handling" (medium.com) — seen in search results on November 6, 2026; the three-package overview.

Frequently Asked Questions

Is encoding/json going away now that jsonv2 is stable?

No. The package is covered by the Go 1 compatibility promise, so code using it will keep working indefinitely, and the migration guide is explicit that no migration is required.

The package now runs on the v2 engine, which means it also gets the faster unmarshaling for free. You can keep every existing import and change nothing.

Do I have to migrate my Go project to jsonv2?

No. If your code works on v1, it keeps working, and upgrading to Go 1.27 alone already gives you the faster unmarshal engine underneath.

Migrate when you want the stricter defaults, the streaming interfaces, or the per-call options. A new project should start on v2, because the package documentation says all new usages of JSON in Go should use it.

Will switching to jsonv2 break my API's JSON output?

It can, in exactly the five ways this guide covers: case-sensitive matching, duplicate keys, invalid UTF-8, nil slices and maps, and the redefined omitempty. A sixth, smaller change is that time.Duration no longer has a default representation and now errors. The safe path is to start from DefaultOptionsV1, which reproduces v1 exactly, and disable one compatibility option at a time while your tests run.

Is jsonv2 faster than encoding/json?

For unmarshaling, yes: the Go team's benchmarks show improvements of up to 10x, depending on the workload. For marshaling, no: the Go team says marshaling runs at about the same speed in both versions. The biggest wins come from the streaming interfaces, which let custom marshalers avoid the allocate-and-reparse cycle that slowed v1 down.

What is omitzero, and is it the same as omitempty?

No. omitzero is a new struct tag that omits a field when it holds its zero Go value, and it works identically in v1 and v2.

omitempty in v2 omits a field when it encodes as an empty JSON value, which is a different test. If you used omitempty on a bool, number, pointer, or interface field to mean "omit when zero", switch that field to omitzero.