github.com/mitchellh/mapstructure
Package mapstructure exposes functionality to convert one arbitrary Go type into another, typically to convert a map[string]interface{} into a native Go structure. The Go structure can be arbitrarily complex, containing slices, other structs, etc. and the decoder will properly decode nested maps and so on into the proper structures in the native Go struct. See the examples to see what the decoder is capable of. The simplest function to start with is Decode. When decoding to a struct, mapstructure will use the field name by default to perform the mapping. For example, if a struct has a field "Username" then mapstructure will look for a key in the source value of "username" (case insensitive). You can change the behavior of mapstructure by using struct tags. The default struct tag that mapstructure looks for is "mapstructure" but you can customize it using DecoderConfig. To rename the key that mapstructure looks for, use the "mapstructure" tag and set a value directly. For example, to change the "username" example above to "user": Embedded structs are treated as if they're another field with that name. By default, the two structs below are equivalent when decoding with mapstructure: This would require an input that looks like below: If your "person" value is NOT nested, then you can append ",squash" to your tag value and mapstructure will treat it as if the embedded struct were part of the struct directly. Example: Now the following input would be accepted: When decoding from a struct to a map, the squash tag squashes the struct fields into a single map. Using the example structs from above: Will be decoded into a map: DecoderConfig has a field that changes the behavior of mapstructure to always squash embedded structs. If there are any unmapped keys in the source value, mapstructure by default will silently ignore them. You can error by setting ErrorUnused in DecoderConfig. If you're using Metadata you can also maintain a slice of the unused keys. You can also use the ",remain" suffix on your tag to collect all unused values in a map. The field with this tag MUST be a map type and should probably be a "map[string]interface{}" or "map[interface{}]interface{}". See example below: Given the input below, Other would be populated with the other values that weren't used (everything but "name"): When decoding from a struct to any other value, you may use the ",omitempty" suffix on your tag to omit that value if it equates to the zero value. The zero value of all types is specified in the Go specification. For example, the zero type of a numeric type is zero ("0"). If the struct field value is zero and a numeric type, the field is empty, and it won't be encoded into the destination type. Since unexported (private) struct fields cannot be set outside the package where they are defined, the decoder will simply skip them. For this output type definition: Using this map as input: The following struct will be decoded: mapstructure is highly configurable. See the DecoderConfig struct for other features and options that are supported.
Readme
mapstructure is a Go library for decoding generic map values to structures and vice versa, while providing helpful error handling.
This library is most useful when decoding values from some data stream (JSON,
Gob, etc.) where you don't quite know the structure of the underlying data
until you read a part of it. You can therefore read a map[string]interface{}
and use this library to decode it into the proper underlying native Go
structure.
Standard go get:
$ go get github.com/mitchellh/mapstructure
For usage and examples see the Godoc.
The Decode function has examples associated with it there.
Go offers fantastic standard libraries for decoding formats such as JSON. The standard method is to have a struct pre-created, and populate that struct from the bytes of the encoded format. This is great, but the problem is if you have configuration or an encoding that changes slightly depending on specific fields. For example, consider this JSON:
{
"type": "person",
"name": "Mitchell"
}
Perhaps we can't populate a specific structure without first reading
the "type" field from the JSON. We could always do two passes over the
decoding of the JSON (reading the "type" first, and the rest later).
However, it is much simpler to just decode this into a map[string]interface{}
structure, read the "type" key, then use something like this library
to decode it into the proper structure.
FAQs
Package mapstructure exposes functionality to convert one arbitrary Go type into another, typically to convert a map[string]interface{} into a native Go structure. The Go structure can be arbitrarily complex, containing slices, other structs, etc. and the decoder will properly decode nested maps and so on into the proper structures in the native Go struct. See the examples to see what the decoder is capable of. The simplest function to start with is Decode. When decoding to a struct, mapstructure will use the field name by default to perform the mapping. For example, if a struct has a field "Username" then mapstructure will look for a key in the source value of "username" (case insensitive). You can change the behavior of mapstructure by using struct tags. The default struct tag that mapstructure looks for is "mapstructure" but you can customize it using DecoderConfig. To rename the key that mapstructure looks for, use the "mapstructure" tag and set a value directly. For example, to change the "username" example above to "user": Embedded structs are treated as if they're another field with that name. By default, the two structs below are equivalent when decoding with mapstructure: This would require an input that looks like below: If your "person" value is NOT nested, then you can append ",squash" to your tag value and mapstructure will treat it as if the embedded struct were part of the struct directly. Example: Now the following input would be accepted: When decoding from a struct to a map, the squash tag squashes the struct fields into a single map. Using the example structs from above: Will be decoded into a map: DecoderConfig has a field that changes the behavior of mapstructure to always squash embedded structs. If there are any unmapped keys in the source value, mapstructure by default will silently ignore them. You can error by setting ErrorUnused in DecoderConfig. If you're using Metadata you can also maintain a slice of the unused keys. You can also use the ",remain" suffix on your tag to collect all unused values in a map. The field with this tag MUST be a map type and should probably be a "map[string]interface{}" or "map[interface{}]interface{}". See example below: Given the input below, Other would be populated with the other values that weren't used (everything but "name"): When decoding from a struct to any other value, you may use the ",omitempty" suffix on your tag to omit that value if it equates to the zero value. The zero value of all types is specified in the Go specification. For example, the zero type of a numeric type is zero ("0"). If the struct field value is zero and a numeric type, the field is empty, and it won't be encoded into the destination type. Since unexported (private) struct fields cannot be set outside the package where they are defined, the decoder will simply skip them. For this output type definition: Using this map as input: The following struct will be decoded: mapstructure is highly configurable. See the DecoderConfig struct for other features and options that are supported.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A hospital in Mobile, Alabama, agreed to a settlement in a landmark ransomware death lawsuit, but is now reportedly reconsidering the agreement and refusing to pay.
Security News
A new report explores how advancements in LLMs are enhancing cyber threats, including polymorphic malware, personalized spearphishing, and the risk of hijacking customer service bots.
Security News
ESLint has approved an RFC that adds support for TypeScript configuration files, which is aimed at improving the developer experience and recognizing changes in the evolving JavaScript ecosystem.