---
title: "Migrate from sigs.k8s.io/yaml to oneyaml"
url: https://recursiveai.org/oneyaml/articles/migrate-from-sigs-k8s-yaml/
description: "Swap one Go import to keep your JSON-tagged structs. Check which sigs.k8s.io/yaml calls carry over and which still need the old package."
date: 2026-11-20
author: oneyaml team
---

# Migrate from sigs.k8s.io/yaml to oneyaml

Swap one Go import to keep your JSON-tagged structs. Check which sigs.k8s.io/yaml calls carry over and which still need the old package.

November 20, 2026 · oneyaml team

**oneyaml** is a free, open-source YAML library for Go from Recursive AI, licensed [MIT](https://github.com/recursive-ai-oss/oneyaml-go/blob/7a4c8e39f041b945ee5f121c055f03bc2d7d01d9/LICENSE-MIT) or [Apache-2.0](https://github.com/recursive-ai-oss/oneyaml-go/blob/7a4c8e39f041b945ee5f121c055f03bc2d7d01d9/LICENSE-APACHE). [pkg.go.dev](https://pkg.go.dev/oneyaml.dev/go@v1.0.0) · [GitHub](https://github.com/recursive-ai-oss/oneyaml-go)

`go get oneyaml.dev/go@v1.0.0`

Use the [adapter](https://github.com/recursive-ai-oss/oneyaml-go/blob/7a4c8e39f041b945ee5f121c055f03bc2d7d01d9/docs/migrate-sigs-k8s-yaml.md#L3-L13) to keep your `yaml` calls, or the native [document API](https://github.com/recursive-ai-oss/oneyaml-go/blob/7a4c8e39f041b945ee5f121c055f03bc2d7d01d9/README.md#L39-L41) to [edit YAML without losing comments](https://recursiveai.org/oneyaml/go/cookbook/edit-yaml-keep-comments/).

*main.go · oneyaml v1.0.0*

```
package main
 
import (
    "fmt"
    "log"
 
    yaml "oneyaml.dev/go/compat/k8syaml"
)
 
type Port struct {
    Number int `json:"containerPort"`
}
 
func main() {
    var port Port
    data := []byte("containerPort: 8080\n")
    if err := yaml.UnmarshalStrict(data, &port); err != nil {
        log.Fatal(err)
    }
    fmt.Println(port.Number)
    out, err := yaml.Marshal(port)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(string(out))
}
```

*Output · Both imports*

```
8080
containerPort: 8080
```

## What changes in the import swap

In a Go module, save the example as `main.go` and run `go run .`. The adapter’s package name is still `yaml`.

To run the original version in a separate module, install `sigs.k8s.io/yaml@v1.6.0` with `go get` and change only the quoted import path to `"sigs.k8s.io/yaml"`. Both released modules printed the output above. The field is named `Number` in Go and `containerPort` in YAML: that name comes from the `json` tag, not from the Go field name.

[sigs.k8s.io/yaml](https://pkg.go.dev/sigs.k8s.io/yaml@v1.6.0#Unmarshal) binds through `encoding/json` after converting YAML to JSON. The [oneyaml adapter](https://pkg.go.dev/oneyaml.dev/go/compat/k8syaml@v1.0.0) keeps that binding model, including JSON decoder options. Here’s what moves and what stays upstream:

| sigs.k8s.io/yaml v1.6.0 | oneyaml adapter v1.0.0 |
|---|---|
| `Marshal`, `Unmarshal`, `UnmarshalStrict` | Same names and signatures; strict struct decoding rejects duplicate YAML keys and unknown fields. |
| `YAMLToJSON`, `YAMLToJSONStrict`, `JSONToYAML` | Same names and signatures; the strict conversion checks duplicate YAML keys, not struct fields. |
| `JSONOpt`, `DisallowUnknownFields` | Same type shape and function signature; pass them to the adapter’s decode calls. |
| `JSONObjectToYAMLObject`; `kyaml`, `yamlfmt`, `goyaml.v2`, `goyaml.v3` | No adapter equivalent. Keep the upstream imports for those calls. |

Same signatures don’t mean identical results on every manifest. The adapter retains YAML 1.1 scalar handling, including unquoted `yes`, but its [documented differences](https://github.com/recursive-ai-oss/oneyaml-go/blob/7a4c8e39f041b945ee5f121c055f03bc2d7d01d9/docs/migrate-sigs-k8s-yaml.md#L79-L83) include preserving the precision of a float read into a string. Compare decoded values and errors on your own manifests before removing the old dependency, especially if they mix numeric and quoted keys.

## When to use oneyaml’s native API instead

Import `oneyaml.dev/go` when you want to decode YAML directly rather than preserve the JSON conversion path. Native `Unmarshal` takes `oneyaml.KnownFields()` to reject unknown fields; it rejects duplicate keys even without that option. It reads the `yaml` tag first and falls back to `json` only when there’s no `yaml` tag. For the example above, the native calls are `oneyaml.Unmarshal(data, &port, oneyaml.KnownFields())` and `oneyaml.Marshal(port)`; they print the same output. Don’t carry over `JSONOpt` values: the native API takes its own options.

Start with the adapter if your goal is a small dependency change. Choose the native API when you’re ready to audit tags and decoding behavior. See the [Go migration reference](https://recursiveai.org/oneyaml/go/docs/migrate-sigs-k8s-yaml/) for the rest of the behavior changes.
