Repository navigation
encoding/json/v2: add new JSON API behind a GOEXPERIMENT=jsonv2 guard #71845
Description
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/v2andencoding/json/jsontextpackages will exist. - The
encoding/jsonpackage will be implemented in terms ofencoding/json/v2. - The
encoding/jsonpackage will include the new APIs proposed in 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.
Activity
mvdan commentedon Feb 23, 2025
Worth noting that one alternative would be to publish the entire code under e.g.
x/exp/jsononce the proposal is approved, and use build tags such as//go:build go1.25to forward the implementation (funcs, types, etc) to std once it lands there.I see a few advantages to that mechanism:
CUE_EXPERIMENTknob 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.x/exp/jsonfirst 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 commentedon Feb 23, 2025
given it's already in an external module, I'm not sure what another copy in x/exp would gain us?
mvdan commentedon Feb 23, 2025
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 commentedon Feb 23, 2025
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 commentedon Feb 24, 2025
The primary purpose of this proposal is to make it easier to test the proposed new implementation of the
encoding/jsonpackage. Anx/package doesn't help with that.aclements commentedon Mar 6, 2025
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.
cespare commentedon Mar 6, 2025
aclements commentedon Mar 6, 2025
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
aclements commentedon Mar 12, 2025
@ianlancetaylor and I looked over #71497 and are happy enough with it to move forward with this proposal to expose it behind a GOEXPERIMENT.
34 remaining items
dsnet commentedon Aug 5, 2025
Sure, I'd be happy to. When are we targeting Go 1.25 release?
cherrymui commentedon Aug 5, 2025
Thank you!
Go 1.25 is scheduled to be released next week. We're planning a series of blog posts for 1.25 features after the release. Later August would be a good time, and it could be flexible. Let me know what time is convenient for you. Thanks.
cherrymui commentedon Aug 15, 2025
Hi @dsnet , just follow up on the blog post. Now that Go 1.25 is released, will you be able to work on a draft? Ideally if you could get a draft ready for review around the last week of August, and we can get the blog published in the first week of September, that would great. Let me know what time is convenient for you. Thanks.
cherrymui commentedon Aug 28, 2025
Hi @dsnet , just checking in -- do you have an update on the timeline? Would you be able to prepare the blog draft this week for publishing next week? Let me know what time works best for you. Thanks!
dsnet commentedon Aug 29, 2025
I'll have a CL for the blog post out by EOD, which means that a release next week would be good.
dsnet commentedon Sep 1, 2025
I apologize, I'm out traveling for Labor Day weekend. I have most of it written, hope to send it out soon.
gopherbot commentedon Sep 4, 2025
Change https://go.dev/cl/700377 mentions this issue:
_content/blog/jsonv2-exp.md: new blog post_content/blog/jsonv2-exp.md: new blog post