Migrating a service from JSON v1 to v2 safely

Marshalled by encoding/json/v2 with no options, the booking response of this lesson changes in three places: a passenger’s age of 0 appears, a list of tags that was never set becomes [], and an & loses its escape. Each change is small, and each can break a client that parses the old bytes. Since Go 1.27 the old API already runs on the new implementation, so a migration means moving the calls themselves, and it is a choice.

The safe path: move every call to v2 with DefaultOptionsV1, which writes v1’s bytes, then turn v1’s behaviours off one at a time, each guarded by a contract testcontract test: A test that pins what another party depends on, such as the exact JSON a service sends and the requests it accepts, so that a change to it fails in the test before any client notices., with a way back ready while the toolchain changes. You will choose a strategy, find the options a service depends on and rehearse that way back, on programs and terminal sessions run on Go 1.27.1, and on Go 1.26.8 where a comparison needs the older release.

The v1 API stays, and already runs on v2

Nothing obliges a service to move. encoding/json is covered by the Go 1 compatibility promiseGo 1 compatibility promise: The Go team's stated intent that programs written to the Go 1 specification keep compiling and running correctly, unchanged, in every later Go 1 release, with a few listed exceptions such as security fixes. More in “What Go is and where it fits”, and the Go 1.27 release notes say that the v1 API will continue to be supported and that users are not required to migrate. What changed is underneath: encoding/json is now backed by the v2 implementation, with its behaviour preserved. The notes list three consequences. Unmarshalling is significantly faster, with nothing to do. The exact text of error messages may differ, so a test or a client that compares it can break on the upgrade alone. And a build with GOEXPERIMENTGOEXPERIMENT: An environment variable of the go command that turns experimental features of the toolchain on or off when a program is built. Go 1.25 used GOEXPERIMENT=jsonv2 to enable encoding/json/v2; Go 1.27 offers nojsonv2 to turn its new implementation off.=nojsonv2 restores the original implementation, an opt-out the notes expect to be removed in a future release. Walk through the releases that led here:

Moving the calls to encoding/json/v2 buys the stricter defaults of the previous lesson, options on every call and the streaming methods. It pays off first in code that parses untrusted input, where refusing names written twice and invalid UTF-8 matters, and in new endpoints. For a stable API whose clients you cannot update, the old calls on the new implementation may serve for a long time.

Three ways to move: all at once, option by option, side by side

The migration guide describes three strategies. All at once switches the imports, runs the tests and sets a compatibility option wherever a test fails, which suits a team that can afford surprises. Option by option first moves every call to v2 with DefaultOptionsV1, which the guide calls a trivial and safe change, then turns v2’s behaviours on one at a time, so that a failure points at the last option removed. Side by side runs v1 and v2 on the same calls in production and reports their differences while clients still receive v1’s output; the jsonsplit package of the go-json-experiment project does this, at about twice the marshalling cost for each call it compares. Here is option by option on one booking: its first step, a step later on, and where it ends once every option has gone:

// same_bytes.go: one booking through v1, through v2 with DefaultOptionsV1, through plain v2, and with one option removed.
package main

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

type Passenger struct {
	Name  string `json:"name"`
	Age   int    `json:"age,omitempty"`
	Berth string `json:"berth,omitempty"`
}

type Booking struct {
	PNR        string      `json:"pnr"`
	Passengers []Passenger `json:"passengers"`
	Tags       []string    `json:"tags"`
	Note       string      `json:"note"`
}

func main() {
	b := Booking{
		PNR:        "4521876390",
		Passengers: []Passenger{{Name: "Asha", Age: 34, Berth: "LB"}, {Name: "Ravi"}},
		Note:       "veg & window",
	}
	want, _ := jsonv1.Marshal(b)
	fmt.Printf("v1:\n  %s\n", want)

	steps := []struct {
		name string
		opts []json.Options
	}{
		{"v2 with DefaultOptionsV1", []json.Options{jsonv1.DefaultOptionsV1()}},
		{"v2 with DefaultOptionsV1, FormatNilSliceAsNull(false)", []json.Options{jsonv1.DefaultOptionsV1(), json.FormatNilSliceAsNull(false)}},
		{"v2 with no options", nil},
	}
	for _, s := range steps {
		got, err := json.Marshal(b, s.opts...)
		if err != nil {
			fmt.Println(s.name+":", err)
			continue
		}
		fmt.Printf("%s: same bytes as v1: %v\n  %s\n", s.name, bytes.Equal(got, want), got)
	}

	// Decoding goes through the same options: a client that sends "PNR" in capitals.
	in := []byte(`{"PNR":"4521876391","tags":["tatkal"]}`)
	var a, c Booking
	_ = jsonv1.Unmarshal(in, &a)
	_ = json.Unmarshal(in, &c, jsonv1.DefaultOptionsV1())
	var d Booking
	_ = json.Unmarshal(in, &d)
	fmt.Printf("decode %s:\n  v1 pnr=%q, v2 with DefaultOptionsV1 pnr=%q, v2 with no options pnr=%q\n", in, a.PNR, c.PNR, d.PNR)
}

v1:
  {"pnr":"4521876390","passengers":[{"name":"Asha","age":34,"berth":"LB"},{"name":"Ravi"}],"tags":null,"note":"veg \u0026 window"}
v2 with DefaultOptionsV1: same bytes as v1: true
  {"pnr":"4521876390","passengers":[{"name":"Asha","age":34,"berth":"LB"},{"name":"Ravi"}],"tags":null,"note":"veg \u0026 window"}
v2 with DefaultOptionsV1, FormatNilSliceAsNull(false): same bytes as v1: false
  {"pnr":"4521876390","passengers":[{"name":"Asha","age":34,"berth":"LB"},{"name":"Ravi"}],"tags":[],"note":"veg \u0026 window"}
v2 with no options: same bytes as v1: false
  {"pnr":"4521876390","passengers":[{"name":"Asha","age":34,"berth":"LB"},{"name":"Ravi","age":0}],"tags":[],"note":"veg & window"}
decode {"PNR":"4521876391","tags":["tatkal"]}:
  v1 pnr="4521876391", v2 with DefaultOptionsV1 pnr="4521876391", v2 with no options pnr=""

With DefaultOptionsV1 the bytes were v1’s, and so was the decoding of PNR in capitals. Turning off one option, FormatNilSliceAsNull, changed one member: tags became []. Plain v2 changed three, and stopped decoding PNR. Which strategy fits depends on your clients and your tests; answer three questions about your service:

Whichever way you move, three tools make the move safe:

• DefaultOptionsV1 is 21 options, and turning each off alone against your own payloads shows which of them your API needs.
• A golden contract test compares what a service sends and accepts with what v1 did, so a change that a client would see fails a test first.
• A build with GOEXPERIMENT=nojsonv2 takes a service back to the original v1 implementation after an upgrade goes wrong.

Which compatibility options your API needs, found by bisection Pro: opens with a Pro, Premium or Ultimate pass

Contract tests and a shadow comparison that catch changes before clients do Pro: opens with a Pro, Premium or Ultimate pass

What Go 1.27 changes on its own, and a rollback rehearsed Pro: opens with a Pro, Premium or Ultimate pass

Practise

The questions cover whether to move and how, starting with the idea you know least:

Interview questions

Warm-up (fresher): Do you have to change code from encoding/json to encoding/json/v2 when you upgrade to Go 1.27?

No. encoding/json stays under the Go 1 compatibility promise, and the Go 1.27 release notes say users are not required to migrate. The upgrade does change what runs underneath: encoding/json is backed by the v2 implementation, with its behaviour preserved, faster unmarshalling, and error messages whose exact text may differ. A build with GOEXPERIMENT=nojsonv2 restores the original implementation if that causes a problem. Moving calls to v2 is worth it for its stricter defaults and per-call options, done step by step with tests.

Three longer questions of the module bank build on this lesson:

Key takeaways

• Moving to encoding/json/v2 is optional: encoding/json stays supported, and since Go 1.27 it already runs on the v2 implementation, with faster unmarshalling and error text that may differ.
• Of the three strategies, option by option starts from DefaultOptionsV1, the same bytes as v1, and changes one behaviour at a time; side by side compares v1 and v2 on live calls at about twice the marshalling cost.
• One option removed changes exactly the members it governs, as FormatNilSliceAsNull changed only tags.