go-viper/mapstructure

The mapstructure library is used for decoding generic map values (like map[string]interface{}) into native Go structures.

It is particularly useful when dealing with data streams (JSON, Gob, etc.) where the schema is not fully known until part of the data is read. For example, if a JSON object contains a type field that determines which struct should be used for the rest of the data, you can:

1. Decode the initial data into a map[string]interface{}.
2. Inspect the specific field (e.g., type).
3. Use mapstructure to decode that map into the appropriate, specific Go struct.

This repository is the maintained fork of the original mitchellh/mapstructure library. Because the API is identical, you can migrate by updating your import paths to github.com/go-viper/mapstructure/v2.

To automate the migration, you can use this sed command to replace all occurrences in your .go files:

sed -i 's|github.com/mitchellh/mapstructure|github.com/go-viper/mapstructure/v2|g' $(find . -type f -name '*.go')

If you are not ready to update your imports immediately, you can use the Go modules replace directive to use the backported fixes from this repository while still using the old import path:

replace github.com/mitchellh/mapstructure => github.com/go-viper/mapstructure v1.6.0

To use mapstructure in your Go project, install the v2 module using go get:

go get github.com/go-viper/mapstructure/v2

To provide custom decoding logic for a specific type, implement the Unmarshaler interface. The decoder checks for this interface on both value and pointer receivers.

When the decoder encounters a type that implements Unmarshaler, it will call the implementation instead of using its default reflection-based decoding logic. The decoder is optimized to check for pointer receivers first, as they are the most common implementation pattern.

By default, embedded structs are treated as nested fields. If your input data is not nested but you want to decode it into an embedded struct, use the ,squash tag option.

Using the ,squash tag

type Person struct {
    Name string
}

type Friend struct {
    Person `mapstructure:",squash"` // fields from Person are treated as part of Friend
}

// Input map[string]any{"name": "alice"} will now work for Friend

Alternatively, you can enable global squashing for all embedded structs by setting Squash: true in the DecoderConfig.

If you want to capture all keys from the source that were not mapped to specific struct fields, use the ,remain tag on a field that is a map type (e.g., map[string]any).

type Friend struct {
    Name  string         `mapstructure:"name"` 
    Other map[string]any `mapstructure:",remain"` // captures everything else
}

// Input: map[string]any{"name": "bob", "address": "123 Maple St."}
// Result: Name="bob", Other=map[string]any{"address": "123 Maple St."}

You can control how fields are mapped using the mapstructure tag. The default tag name is mapstructure, but this can be changed in DecoderConfig.TagName.

Renaming Fields

To map a specific key to a field, set the tag value to the desired key name:

type User struct {
    Username string `mapstructure:"user"` // matches key "user"
}

Ignoring Fields

To prevent a field from being decoded, use a hyphen:

type User struct {
    Password string `mapstructure:"-"`
}

When decoding from a struct to another type, you can use tags to skip fields based on their value:

• ,omitempty: Omits the field if it is the zero value for its type or a zero-length element (like an empty slice).
• ,omitzero: Omits the field if it is the zero value. Note that for slices, an empty but non-nil slice will still be encoded, whereas omitempty would omit it.

type Source struct {
    Age  int      `mapstructure:",omitempty"` 
    URLs []string `mapstructure:",omitzero"` 
}

When WeaklyTypedInput is enabled in the decoder configuration, mapstructure provides flexible conversion logic for slices and arrays:

• Empty Maps: An empty map in the source data will be converted into an empty slice or array in the target.
• Single Values: If the source data is a single value (e.g., a string) and the target is a slice (e.g., []string), the decoder will "lift" the single value into a slice containing that one element.
• Byte Slices: A string in the source data can be automatically converted into a []byte in the target.
• Map to Slice: If the source is a map and the target is a slice, the decoder will attempt to treat the map as a slice of maps.

Use ComposeDecodeHookFunc to create a single DecodeHookFunc that chains multiple hooks together. The hooks are executed in the order they are provided, and the output of one hook is passed as the input to the next. If any hook in the chain returns an error, the entire composition returns that error.

// Example of composing hooks
hook := mapstructure.ComposeDecodeHookFunc(
    mapstructure.StringToTimeDurationHookFunc(),
    mapstructure.StringToIPHookFunc(),
)