proposal: encoding/json: include field name in unmarshal error messages for types that implement UnmarshalJSON

[MadLittleMods]

Proposal Details

Problem context

The following example just outputs panic: unhelpful error which isn't useful in finding out which key in the JSON caused the problem, i.e "was it bar or baz that caused the problem?" We only have access to the value bytes (no key name) so even if we wanted to write a better error message, we couldn't.

• Playground link
• Output: panic: unhelpful error

package main

import (
	"encoding/json"
	"errors"
	"fmt"
)

type strawberry struct{}

func (b *strawberry) UnmarshalJSON(data []byte) error {
	return errors.New("unhelpful error")
}

type myType struct {
	Foo string     `json:"foo,omitempty"`
	Bar strawberry `json:"bar,omitempty"`
	Baz strawberry `json:"baz,omitempty"`
}

func main() {
	json_bytes := []byte(`{ "foo": "test", "bar": 1, "baz": 2 }`)
	var data myType
	if err := json.Unmarshal(json_bytes, &data); err != nil {
		panic(err)
	}
	fmt.Println(data)
}

Compare this with the built-in types where we get some helpful output -> panic: json: cannot unmarshal number into Go struct field myType.bar of type string because of the automatic logic behind json.UnmarshalTypeError (see addErrorContext).

• Playground link
• Output: panic: json: cannot unmarshal number into Go struct field myType.bar of type string

package main

import (
	"encoding/json"
	"fmt"
)

type myType struct {
	Foo string `json:"foo,omitempty"`
	Bar string `json:"bar,omitempty"`
	Baz string `json:"baz,omitempty"`
}

func main() {
	json_bytes := []byte(`{ "foo": "test", "bar": 1, "baz": 2 }`)
	var data myType
	if err := json.Unmarshal(json_bytes, &data); err != nil {
		panic(err)
	}
	fmt.Println(data)
}

We can partially get our desired effect by returning json.UnmarshalTypeError ourselves but it doesn't allow for any extra context on why we failed to parse it. For example, what if the reason we failed to unmarshal was because Strawberries have at-least 200 seeds but there is not place to add this context with the current json.UnmarshalTypeError.

• Playground link
• Output: panic: json: cannot unmarshal 1 into Go struct field myType.bar of type main.strawberry

package main

import (
	"encoding/json"
	"fmt"
	"reflect"
)

type strawberry struct{}

func (b *strawberry) UnmarshalJSON(data []byte) error {
	return &json.UnmarshalTypeError{Value: string(data), Type: reflect.TypeOf((*strawberry)(nil)).Elem(), Offset: 0}
}

type myType struct {
	Foo string     `json:"foo,omitempty"`
	Bar strawberry `json:"bar,omitempty"`
	Baz strawberry `json:"baz,omitempty"`
}

func main() {
	json_bytes := []byte(`{ "foo": "test", "bar": 1, "baz": 2 }`)
	var data myType
	if err := json.Unmarshal(json_bytes, &data); err != nil {
		panic(err)
	}
	fmt.Println(data)
}

Proposal

Wrap any error from UnmarshalJSON and include the field name context that generated the error.

Another possibility is to extend json.UnmarshalTypeError to allow for additional custom error context which would work but not everyone is going to be as meticulous to always return json.UnmarshalTypeError to get the benefits.

I'm not writing Go everyday so there is probably a better strategy as well.

Related issues

• encoding/json: include field name in unmarshal error messages #6716

[ianlancetaylor]

Thanks. At present any proposals for encoding/json should be directed at encoding/json/v2 instead. See #71497 .

[gabyhelp]

Related Issues

• proposal: encoding/json: wrap error from TextUnmarshaler/Unmarshaler to locate the problem in input #58655
• encoding/json: UnmarshalTypeError is clobbered when using nested custom marshallers #61337 (closed)
• encoding/json: UnmarshalTypeError should tell you what key you were unmarshaling #8254 (closed)
• encoding/json: Unmarshal cannot unmarshal X into Go value of type Y does not tell you the field name #10141 (closed)
• proposal: encoding/json: add support of wrapped error in addErrorContext function #45449
• encoding/json: include field name in unmarshal error messages #6716 (closed)
• encoding/json: UnmarshalTypeError.Error message seems insensible #43126
• proposal: encoding/json: add error var to compare the returned error when using json.Decoder.DisallowUnknownFields() #29035

Related Code Changes

• encoding/json: add embedded structs to the UnmarshalTypeError's Field
• encoding/json: add struct and field name to UnmarshalTypeError message

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

[MadLittleMods]

Closing in favor of #58655 ⏩

Other related issues:

• proposal: encoding/json: add support of wrapped error in addErrorContext function  #45449