The Go blog announces the stable JSON v2 packages as part of the Go 1.27 release.
GO LANG RELEASES STABLE JSON V2 API IN VERSION 1.27
*Go 1.27 introduces a stable second‑generation JSON library, fixing long‑standing bugs and security gaps in the original encoding/json package. The overhaul brings stricter RFC compliance, streaming support, and performance gains that developers have demanded for years.*
The Go team announced that Go 1.27 ships with a stable, second‑generation JSON library: encoding/json/v2 and encoding/json/jsontext. After a year of experimental releases and community feedback, the new API replaces the long‑standing encoding/json package that has been part of the language since before Go 1.0. The change arrives at a time when JSON remains the dominant data‑interchange format on the internet, and Go programs routinely marshal and unmarshal billions of JSON messages every day.
The original package earned a reputation for flexibility, but users have catalogued a litany of shortcomings. Decoders silently accepted invalid UTF‑8, ignored duplicate object keys, and marshaled nil slices and maps as JSON nulls—behaviors that clash with RFC 8259 and break interoperability. Case‑insensitive field matching introduced subtle security risks, while the API forced developers to juggle separate Encoder and Decoder options that could not be propagated through custom MarshalJSON or UnmarshalJSON methods. Performance suffered from mandatory full‑value parsing and quadratic costs when custom methods recursed. The Go team set out to fix these flaws without breaking existing code.
What problems plagued the original encoding/json?
The legacy encoding/json package suffered from both behavioral and API defects. It accepted invalid UTF‑8 despite RFC 8259’s requirement for valid encoding, and it allowed objects with duplicate member names, a loophole that enabled attacks such as CVE‑2017‑12635. Nil slices and maps were emitted as JSON null, breaking programs that expected empty arrays or objects. Unmarshaling matched struct fields case‑insensitively, creating surprising mappings and a potential attack surface. API-wise, developers struggled to reject trailing junk, propagate options through custom MarshalJSON/UnmarshalJSON methods, and use Compact, Indent, or HTMLEscape with flexible writers. These issues forced workarounds and limited the package’s suitability for high‑performance or security‑critical workloads.
Why does the new Go JSON API matter for security?
The v2 implementation closes the most exploitable gaps. It now rejects invalid UTF‑8 by default, aligning Go with the Internet Standard and preventing silent data corruption. Duplicate object keys trigger an error instead of yielding ambiguous values, removing the attack vector demonstrated in CVE‑2017‑12635. Nil slices and maps are marshaled as empty arrays or objects, preserving compatibility with strict JSON parsers. Case‑insensitive field matching has been eliminated, forcing explicit struct tags and eliminating surprising mappings. Together, these changes raise the baseline security posture of every Go service that consumes or produces JSON, from micro‑services to cloud‑native APIs.
How does the new API improve performance and streaming?
The new packages expose a token‑level API that streams directly from io.Reader and writes to any io.Writer without buffering the whole document. Decoder.Token has been re‑engineered to avoid heavy allocations, and Encoder now supports incremental token emission. MarshalJSON no longer forces an allocation of the returned []byte; the library validates JSON on the fly, cutting the double‑parse penalty. UnmarshalJSON receives a slice that ends at the first non‑JSON byte, eliminating the need to scan the entire input before invoking custom logic. These refinements shrink memory footprints, lower latency, and prevent the quadratic slowdown that plagued recursive MarshalJSON calls in the legacy library.
What does the rollout mean for Go developers?
Go 1.27 ships the v2 packages as stable, generally available code. Existing projects can import encoding/json/v2 alongside the classic package, allowing a gradual migration. The new API offers configurable Encoder and Decoder options that propagate through custom MarshalJSON and UnmarshalJSON implementations, fixing a long‑standing pain point. Developers gain stricter validation, safer defaults, and streaming‑friendly functions without sacrificing the familiar marshaling semantics. Early adopters report reduced memory usage and faster JSON processing in benchmark suites. The Go team’s decision to release a major version rather than a patch underscores the depth of the changes and signals that future Go releases will build on this modernized foundation.
Frequently asked questions
What are the main flaws of Go's original encoding/json package?
It accepted invalid UTF-8, allowed duplicate object member names, marshaled nil slices and maps as JSON null, performed case‑insensitive field matching, and had API limitations that prevented option propagation and proper trailing‑data rejection.
When did the new JSON v2 API become generally available?
The new encoding/json/v2 and encoding/json/jsontext packages are stable and generally available in Go 1.27, announced on 4 November 2026.
Which past vulnerability exploited duplicate JSON member names?
The duplicate‑key issue has been exploited before, as documented in CVE-2017-12635.
With the v2 JSON library now baked into Go 1.27, the language closes a decade‑long gap between developer expectations and the realities of modern data exchange. Security‑first defaults, streaming support, and a leaner performance profile will ripple through the Go ecosystem, from cloud services to embedded systems. The move also sets a precedent: core libraries will no longer tolerate legacy quirks when they jeopardize safety or efficiency. Expect a wave of updates as teams refactor code to leverage the safer, faster API.
Sources: https://go.dev/blog/jsonv2, Hacker News