---
title: "Decode a YAML scalar into a custom Go type"
url: https://recursiveai.org/oneyaml/go/cookbook/read-yaml-into-custom-go-type/
description: "Implement UnmarshalYAML in Go to decode a YAML duration string into a custom Timeout type and return an error when the unit is missing."
version: "1.0.0"
---

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

[pkg.go.dev](https://pkg.go.dev/oneyaml.dev/go) · [GitHub](https://github.com/recursive-ai-oss/oneyaml-go) · [Docs](https://recursiveai.org/oneyaml/go/docs/) · [Download example (.zip)](https://recursiveai.org/oneyaml/go/cookbook/read-yaml-into-custom-go-type/read-yaml-into-custom-go-type.zip)

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

```shell
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](https://recursiveai.org/oneyaml/go/cookbook/read-yaml-into-custom-go-type/read-yaml-into-custom-go-type.zip), 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"
```

## Related recipes

- [Parse YAML into Go structs](https://recursiveai.org/oneyaml/go/cookbook/parse-yaml-into-structs/)
- [Decode a YAML string or list](https://recursiveai.org/oneyaml/go/cookbook/decode-flexible-yaml-list/)

## 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`](https://pkg.go.dev/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](https://recursiveai.org/oneyaml/go/docs/migrate-yaml-v3/#hooks).

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.
