Implement UnmarshalYAML on *Timeout to read 1500ms as a Go duration.
go get oneyaml.dev/goRequires Go 1.24+. Run in a Go module.
package main import ( "fmt" "log" "time" "oneyaml.dev/go" ) type Timeout time.Duration func (t *Timeout) UnmarshalYAML( decode func(any) error, ) error { var text string if err := decode(&text); err != nil { return err } duration, err := time.ParseDuration(text) if err == nil { *t = Timeout(duration) } return err } func main() { input := []byte("timeout: 1500ms\n") var cfg struct { Timeout Timeout `yaml:"timeout"` } err := oneyaml.Unmarshal(input, &cfg) if err != nil { log.SetFlags(0) log.Fatal(err) } fmt.Println(time.Duration(cfg.Timeout)) }
Unzip the example, then go run ..
1.5sIf the value can’t be parsed as a Go duration, Unmarshal reports the error on the timeout field.
Variations
Read minutes and seconds. Replace the input assignment:
input := []byte("timeout: 1m30s\n")1m30sReject a duration without a unit. Replace the input assignment with this line:
input := []byte("timeout: 1500\n")The program prints this error to standard error and exits with status 1:
oneyaml: line 1, column 10: /timeout: time: missing unit in duration "1500"Related recipes
The short answer
Put UnmarshalYAML(decode func(any) error) error on a pointer to your field’s type. Use decode to read the YAML value into an ordinary Go string, then parse the string for your application. Assign the result to the receiver only if parsing succeeds. In this recipe Timeout is a defined type based on time.Duration, so a field of that type can accept duration text directly.
How do I implement UnmarshalYAML on a custom Go type?
Start by deciding what textual form the field should accept. Here it’s whatever time.ParseDuration understands, including 1500ms and 1m30s. The callback reads just the value assigned to the field, not the whole mapping. Decode into a temporary string, not into Timeout again; decoding into the same custom type would invoke its hook again. A pointer receiver lets the hook store the parsed duration back into the field.
oneyaml-go accepts UnmarshalYAML(func(any) error) error or UnmarshalYAML(oneyaml.Node) error, not a hook that takes the original *yaml.Node; see the yaml.v3 migration guide.
Keep the hook on the domain type rather than making it responsible for every field on the config struct. Another struct can then use Timeout and get the same decoding behavior. Keep fields as strings if you need to preserve the spelling of the input. In the example, 1500ms prints as 1.5s because the result is a duration, not the original text.
How do I unmarshal a YAML duration string into a Go struct?
Declare the field with the custom type and give it the tag yaml:"timeout". When Unmarshal reads the timeout key, the type’s hook converts the value. This puts the conversion next to the field declaration: code using the config can turn it into a time.Duration directly instead of parsing it every time it needs a timeout.
Decoding and validation still have different jobs. A valid duration such as -1s can be parsed, so check positivity separately if your application requires it. If the field is absent, the custom conversion can’t tell you that a required setting was omitted. Check required fields when you validate the config. If you only need to parse one field in one place, an ordinary string field followed by a call to time.ParseDuration is also an option.