encoding/json: key type implementing json.Unmarshaler cannot be unmarshaled (documentation bug)

[bserdar]

Go version

go version go1.22.1 linux/amd64

Output of go env in your module/workspace:

GO111MODULE=''
GOARCH='amd64'
GOBIN=''
GOCACHE='/home/bserdar/.cache/go-build'
GOENV='/home/bserdar/.config/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFLAGS=''
GOHOSTARCH='amd64'
GOHOSTOS='linux'
GOINSECURE=''
GOMODCACHE='/home/bserdar/go/pkg/mod'
GONOPROXY='gitlab.com'
GONOSUMDB='gitlab.com'
GOOS='linux'
GOPATH='/home/bserdar/go'
GOPRIVATE='gitlab.com'
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/usr/local/go'
GOSUMDB='sum.golang.org'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/usr/local/go/pkg/tool/linux_amd64'
GOVCS=''
GOVERSION='go1.22.1'
GCCGO='gccgo'
GOAMD64='v1'
AR='ar'
CC='gcc'
CXX='g++'
CGO_ENABLED='1'
GOMOD='/dev/null'
GOWORK=''
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
PKG_CONFIG='pkg-config'
GOGCCFLAGS='-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=/tmp/go-build3704543572=/tmp/go-build -gno-record-gcc-switches'

What did you do?

The json unmarshal documentation claims that:

The map's key type must either be any string type, an integer, implement json.Unmarshaler, or implement encoding.TextUnmarshaler.

So I did this:

https://go.dev/play/p/bwYpWzHkfKC

What did you see happen?

A key type implementing json.Unmarshaler cannot be unmarshaled. If key type implements TextUnmarshaler, JSON unmarshaling works as expected.

What did you expect to see?

This is probably a documentation issue. The documentation for json.Marshal does not require the key type to implement json.Marshaler, but the documentation for json.Unmarshal claims it should work. So I believe the documentation for json.Unmarshal should be corrected to not say a key type implementation should implement json.Unmarshaler.

[seankhliao]

Looks like the docs for Marshal are correct, but Unmarshal is wrong.