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.
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)) }
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.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 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.