Recursive AI

Decode a YAML scalar into a custom Go type

oneyaml-go is a free, open-source YAML library for Go from Recursive AI. MIT or Apache-2.0, no dependencies.

Implement UnmarshalYAML on *Timeout to read 1500ms as a Go duration.

Terminal
go get oneyaml.dev/go

Requires Go 1.24+. Run in a Go module.

GO
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 ..

Text
1.5s

If 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:

GO
input := []byte("timeout: 1m30s\n")
Text
1m30s

Reject a duration without a unit. Replace the input assignment with this line:

GO
input := []byte("timeout: 1500\n")

The program prints this error to standard error and exits with status 1:

Text
oneyaml: line 1, column 10: /timeout: time: missing unit in duration "1500"

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.

All oneyaml Go recipes