Overview¶

The jsonimports tool formats all Go source files in the repositoryto enforce that "json" imports are consistent.

With Go 1.25, the "encoding/json/v2" and "encoding/json/jsontext"packages are now available under goexperiment.jsonv2.This leads to possible confusion over the following:

• "encoding/json"
• "encoding/json/v2"
• "encoding/json/jsontext"
• "github.com/go-json-experiment/json/v1"
• "github.com/go-json-experiment/json"
• "github.com/go-json-experiment/json/jsontext"

In order to enforce consistent usage, we apply the following rules:

• Until the Go standard library formally accepts "encoding/json/v2"and "encoding/json/jsontext" into the standard library(i.e., they are no longer considered experimental),we forbid any code from directly importing those packages.Go code should instead import "github.com/go-json-experiment/json"and "github.com/go-json-experiment/json/jsontext".The latter packages contain aliases to the standard libraryif built on Go 1.25 with the goexperiment.jsonv2 tag specified.

• Imports of "encoding/json" or "github.com/go-json-experiment/json/v1"must be explicitly imported under the package name "jsonv1".If both packages need to be imported, then the former shouldbe imported under the package name "jsonv1std".

• Imports of "github.com/go-json-experiment/json"must be explicitly imported under the package name "jsonv2".

The latter two rules exist to provide clarity when reading code.Without them, it is unclear whether "json.Marshal" refers to v1 or v2.With them, however, it is clear that "jsonv1.Marshal" is calling v1 andthat "jsonv2.Marshal" is calling v2.

TODO(@joetsai): At this present moment, there is no guidance given onwhether to use v1 or v2 for newly written Go source code.I will write a document in the near future providing more guidance.Feel free to continue using v1 "encoding/json" as you are accustomed to.