oneyaml Go docs
Everything about oneyaml for Go: getting started, editing, patches, limits, moving from yaml.v3 and sigs.k8s.io/yaml, how it compares, and the reference.
Start
Getting startedInstall the module, read YAML into Go structs, write it back, edit a document in place and keep its comments, and apply JSON Patch and merge patches.OverviewThe module README: what oneyaml-go is, the quick start, when to use it and when not, correctness, the yaml.v3 and sigs.k8s.io/yaml adapters, and stability.
Guides
EditingHow Document changes a YAML file and what it promises to leave alone. For the API reference see pkg.go.dev; for patches see Patches.PatchesHow to apply a patch to a YAML file. The operations are those of JSON Patch (RFC 6902), the paths are JSON Pointers (RFC 6901), and merge patches follow JSON Merge Patch (RFC 7396), but they are applied to YAML with YAML's data model, not to JSON. The edits follow the rules…LimitsLimits stop input from using more time or memory than you intended. By default, nesting depth, alias expansion, the digits of a number and the work of a patch are bounded. Input size, documents per stream and scalar length are bounded only when you select Untrusted(); select…
Migrating
From yaml.v3Two ways to move from gopkg.in/yaml.v3 (or go.yaml.in/yaml/v3): keep your code and swap the import to the compat/yamlv3 adapter, or move to the oneyaml API. The first keeps your call sites, and the checklist below covers where its behaviour can differ. The second reads YAML…From sigs.k8s.io/yamlTwo ways to move from sigs.k8s.io/yaml (and its parent ghodss/yaml): keep your code and swap the import to the compat/k8syaml adapter, or move to the oneyaml API. sigs.k8s.io/yaml converts YAML to JSON and lets encoding/json bind it, so what it reads is what the JSON round…
Choosing
ComparisonHow oneyaml-go compares with the Go YAML libraries it is most often weighed against: gopkg.in/yaml.v3 (and its maintained fork go.yaml.in/yaml/v3), its prerelease successor go.yaml.in/yaml/v4, sigs.k8s.io/yaml and github.com/goccy/go-yaml.PerformanceThis page compares the time and memory of oneyaml-go with those of the other Go YAML libraries. Every library runs the same tasks on the same inputs, through the benchmark of oneyaml-kit, the kit shared by the oneyaml libraries. The tables under Results are generated from the…
Reference
ConformanceWhat oneyaml-go is measured against, the latest results, and every case it is known not to pass.ChangelogAll notable changes are listed here, newest first. The format follows Keep a Changelog, and versions follow Semantic Versioning. Breaking changes are listed first, under Breaking, each with what to change in your code (releases up to 0.3.0 mark them Breaking instead). A new…