Merge pull request #137 from andreev-fn/opt-root-name

sagikazarmark · web-flow · commit fd74c75bae0e · 2026-01-12T16:41:33.000+01:00
feat: optional root object name
diff --git a/mapstructure.go b/mapstructure.go
@@ -302,6 +302,10 @@ type DecoderConfig struct {
 	// matching non-empty tag will be used.
 	TagName string
 
+	// RootName specifies the name to use for the root element in error messages. For example:
+	//   '<rootName>' has unset fields: <fieldName>
+	RootName string
+
 	// The option of the value in the tag that indicates a field should
 	// be squashed. This defaults to "squash".
 	SquashTagOption string
@@ -491,7 +495,7 @@ func NewDecoder(config *DecoderConfig) (*Decoder, error) {
 // Decode decodes the given raw interface to the target pointer specified
 // by the configuration.
 func (d *Decoder) Decode(input any) error {
-	err := d.decode("", input, reflect.ValueOf(d.config.Result).Elem())
+	err := d.decode(d.config.RootName, input, reflect.ValueOf(d.config.Result).Elem())
 
 	// Retain some of the original behavior when multiple errors ocurr
 	var joinedErr interface{ Unwrap() []error }
diff --git a/mapstructure_test.go b/mapstructure_test.go
@@ -3900,6 +3900,58 @@ func TestDecode_structArrayDeepMap(t *testing.T) {
 	}
 }
 
+func TestDecoder_RootName(t *testing.T) {
+	t.Parallel()
+
+	input := map[string]any{
+		"surname": "green",
+		"relation": map[string]any{
+			"surname": "black",
+		},
+	}
+
+	var result struct {
+		Name     string `mapstructure:"name"`
+		Relation struct {
+			Name string `mapstructure:"name"`
+		} `mapstructure:"relation"`
+	}
+
+	decoder, err := NewDecoder(&DecoderConfig{
+		ErrorUnset:  true,
+		ErrorUnused: true,
+		Result:      &result,
+		RootName:    "root",
+	})
+	if err != nil {
+		t.Fatalf("err: %s", err)
+	}
+
+	err = decoder.Decode(input)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+
+	expectedErrors := []string{
+		`'root.relation' has invalid keys: surname`,
+		`'root.relation' has unset fields: name`,
+		`'root' has invalid keys: surname`,
+		`'root' has unset fields: name`,
+	}
+
+	failed := false
+
+	for _, expectedErr := range expectedErrors {
+		if !strings.Contains(err.Error(), expectedErr) {
+			failed = true
+		}
+	}
+
+	if failed {
+		t.Errorf("unexpected error message, got: %s", err.Error())
+	}
+}
+
 func stringPtr(v string) *string  { return &v }
 func intPtr(v int) *int           { return &v }
 func uintPtr(v uint) *uint        { return &v }
