proposal: encoding/json/v2: add new JSON API behind a GOEXPERIMENT=jsonv2 guard

[neild]

This is an adjunct proposal to #71497.

#71497 proposes adding a new JSON API, consisting of encoding/json/v2 and encoding/json/jsontext packages. The existing encoding/json package is modified to use the new v2 implementation internally. Several new functions are added to encoding/json. See that proposal for details.

The proposed new API is implemented in github.com/go-json-experiment/json.

I propose that we merge the implementation in github.com/go-json-experiment/json into std immediately, enabled only when the GOEXPERIMENT=jsonv2 experiment flag is set.

When the jsonv2 experiment flag is not enabled, there will be no user-visible changes to std. The encoding/json package will exist exactly as it is now, and the proposed new packages will not exist.

When GOEXPERIMENT=jsonv2 is set:

• The new encoding/json/v2 and encoding/json/jsontext packages will exist.
• The encoding/json package will be implemented in terms of encoding/json/v2.
• The encoding/json package will include the new APIs proposed in proposal: encoding/json/v2: new API for encoding/json #71497.

The experimental API will not be bound by the Go compatibility promise and will evolve as updates are made to #71497.

If #71497 isn't approved in time for Go 1.25, we can either ship 1.25 with the GOEXPERIMENT guard or revert the experimental API in the 1.25 release. If #71497 is rejected, we'll remove the experimental package.

This proposal presumes that while there are still details being resolved, #71497 is on track for acceptance and we're happy with the general structure of the proposed API. Merging it into the main go repository prior to acceptance will make it easier for users to test out the new implementation.

[mvdan]

Worth noting that one alternative would be to publish the entire code under e.g. x/exp/json once the proposal is approved, and use build tags such as //go:build go1.25 to forward the implementation (funcs, types, etc) to std once it lands there.

I see a few advantages to that mechanism:

1. Once the proposal is accepted and the API can be considered frozen, it lets downstreams start using it without waiting for the next Go release. This is particularly important for downstream library projects, as they tend to support two major Go versions. So if we were to merge into std for go1.25.0 being released in August 2025, many downstreams would have to wait until February 2026 to start importing it - even if just to implement new marshaler methods.
2. It skips the CUE_EXPERIMENT knob entirely, which could cause some transition pain over the next year or two, such as some projects not working correctly with (or without) the experiment enabled.
3. Placing the API under x/exp/json first allows us to delay adding it to std until late in the release cycle if we wish to, e.g. go1.25rc.1, reducing the chances that we need to do a big noisy revert if something goes wrong before then.

[seankhliao]

given it's already in an external module, I'm not sure what another copy in x/exp would gain us?

[mvdan]

x/exp is part of the Go project, which brings many benefits - Gerrit, CI, the rest of the reviewers and approvers. Plus, the import path blesses it as official to users, whereas https://github.com/go-json-experiment is pretty much just a third party org.

[seankhliao]

an external module wouldn't benefit any existing users of encoding/json (which right now is ~all of them), without rewriting their imports, and reverting when it's released.
Plus, existing users would be faced with multiple transitions from go-json-experiment -> x/exp -> json/v2
x/exp has the added negative of bringing in a lot of other experimental packages, which aren't fully deprecated yet, but all versioned together.

[neild]

The primary purpose of this proposal is to make it easier to test the proposed new implementation of the encoding/json package. An x/ package doesn't help with that.

[aclements]

This seems reasonable. @ianlancetaylor and I would like to at least look over #71497 because we start moving this forward. We plan to do that in the next week. Assuming it passes our sniff test, I think we can proceed with the GOEXPERIMENT=jsonv2 proposal.

[aclements]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— aclements for the proposal review group