Go json.Unmarshal documentation is misleading about case-insensitive key matching

[vaibhavgholap23]

Go version

go1.21.4 darwin/arm64

Output of go env in your module/workspace:

GO111MODULE=""
GOARCH="arm64"
GOBIN="/Users/gopher/go/bin"
GOCACHE="/Users/gopher/go/cache"
GOENV="/Users/gopher/Library/Application Support/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="arm64"
GOHOSTOS="darwin"
GOINSECURE=""
GOMODCACHE="/Users/gopher/go/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="darwin"
GOPATH="/Users/gopher/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/usr/local/go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/usr/local/go/pkg/tool/darwin_arm64"
GOVCS=""
GOVERSION="go1.21.4"
GCCGO="gccgo"
AR="ar"
CC="clang"
CXX="clang++"
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 -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/44/nbbyll_10jd0z8rj_qxm43740000gn/T/go-build2331607515=/tmp/go-build -gno-record-gcc-switches -fno-common"

What did you do?

I ran the following Go program to test how json.Unmarshal handles case-insensitive JSON keys:

`package main

import (
"encoding/json"
"fmt"
)

type Example struct {
Name string json:"name"
}

func main() {
jsonData := {"name": "Alice", "NAME": "Bob", "Name": "Charlie"}

var e Example
err := json.Unmarshal([]byte(jsonData), &e)
if err != nil {
	fmt.Println("Error:", err)
	return
}

fmt.Println("Result:", e.Name) // Expected: "Alice", Actual: "Charlie"

}`

What did you see happen?

Instead of selecting the first exact match (i.e., "name": "Alice"), json.Unmarshal took the last occurrence of the key, "Name": "Charlie", regardless of case.

Result: Charlie

What did you expect to see?

The Go documentation suggests that json.Unmarshal prefers exact matches first before falling back to case-insensitive matching.

I expected the output to be:
Result: Alice

since "name" is an exact match to the struct tag.

Instead, Go appears to always take the last occurrence in JSON, regardless of case.

[vaibhavgholap23]

Thank you for reviewing this issue! Since this behavior is confirmed, could we update the official encoding/json documentation to clearly state that:

json.Unmarshal does not prioritize exact matches first.

Instead, it follows a last key wins approach, regardless of case.

This clarification would help developers avoid confusion when handling JSON data with duplicate keys in different cases.

Please let me know your thoughts on this! Thanks again for your time. 🙌

[gabyhelp]

Related Issues

• encoding/json: Unmarshal case insensitive match can lead to nondeterministic behavior #36932 (closed)
• encoding/json: need to clarify case sensitivity on Unmarshal documentation? #11673 (closed)
• encoding/json: bug in json.Unmarshal if keys in JSON differ only by case #26687 (closed)
• encoding/json: decoder does not prefer exact match #66589 (closed)
• encoding/json: Capitalization in field tags not handled correctly when unmarshalling #28190 (closed)
• encoding/json: document unmarshalling of lowercase keys into exported struct fields #4664 (closed)
• encoding/json: Unmarshal doesn't use preferred match #47984 (closed)
• json.Unmarshal() documentation doesn't make it clear that struct fields need to be exported #5965 (closed)

Related Code Changes

• encoding/json: clarify how we decode into structs
• encoding/json: correct comment on unmarshalling JSON into structs

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}