Recursive AI

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.

oneyaml is a free, open-source YAML library for Go from Recursive AI, licensed MIT or Apache-2.0. pkg.go.dev · GitHub

go get oneyaml.dev/go@v1.0.0

Use the adapter to keep your yaml calls, or the native document API to edit YAML without losing comments.

main.gooneyaml 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))
}
OutputBoth 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 binds through encoding/json after converting YAML to JSON. The oneyaml adapter keeps that binding model, including JSON decoder options. Here’s what moves and what stays upstream:

sigs.k8s.io/yaml v1.6.0oneyaml adapter v1.0.0
Marshal, Unmarshal, UnmarshalStrictSame names and signatures; strict struct decoding rejects duplicate YAML keys and unknown fields.
YAMLToJSON, YAMLToJSONStrict, JSONToYAMLSame names and signatures; the strict conversion checks duplicate YAML keys, not struct fields.
JSONOpt, DisallowUnknownFieldsSame type shape and function signature; pass them to the adapter’s decode calls.
JSONObjectToYAMLObject; kyaml, yamlfmt, goyaml.v2, goyaml.v3No 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 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 for the rest of the behavior changes.