Repository navigation
go-yaml v4.0.0 #490
Replies: 2 comments 1 reply
|
Congratulations on v4.0.0. oasdiff v1.36.0 shipped today on kin-openapi v0.153.0, so v4 is now in the path of every openapi3 and oasdiff user. Thanks for the reviews that got us there, and for turning #494 around in a day. Four follow-up items our users would appreciate.
The first two are the ones that bite in released code. The last two are papercuts we work around. |
Rationale behind bumping to Go 1.18 as minimal versionFollowing @andygrunwald's question in stretchr/testify#2005, here is some context on why When moving away from Go 1.17, Go 1.18 was picked in #69 (August 2025) as a sensible baseline. Go 1.18 was a major release from March 2022, already over three years old at the time. Sticking to Go 1.17 (released just 7 months prior to 1.18) would have meant targeting an EOL version while missing out on a landmark release, for virtually no practical maintenance gain. Go 1.18 is a good floor for a foundational library: it unlocks modern language features while keeping compatibility with enterprise distros (like RHEL 8 or Ubuntu 22.04 LTS) that still run older toolchains (as discussed in stretchr/testify#2006). While we didn't have a master plan to rewrite everything on day one (aside from adopting
PR #69 set the baseline, and taking advantage of Go 1.18 features happened naturally without prematurely dropping support for long-term enterprise environments. |
Uh oh!
There was an error while loading. Please reload this page.
go-yaml v4.0.0
go-yaml v4.0.0 is the first stable release of the v4 series, maintained by the
YAML organization.
It adds configurable loading and dumping, public plugin interfaces, structured
errors, and a CLI for inspecting YAML processing.
The classic APIs remain supported, so applications can adopt v4 incrementally.
Getting started
Install the release:
Use this import path in your Go code:
For an existing v3 application, start by updating imports, reviewing custom
unmarshalers, and running your tests.
You can continue using
Unmarshal,Marshal,NewDecoder, andNewEncoder.The v2 and v3 APIs remain frozen, with security fixes only; new features and
routine bug fixes are developed in v4.
Why add Load and Dump?
Applications need different YAML policies: strict configuration validation,
particular output layouts, or custom anchor handling.
The new
LoadandDumpfunctions and streamingLoaderandDumperacceptfunctional options and plugins for those choices.
They use YAML's load/dump terminology and are recommended for new code.
The classic entry points keep compatibility settings rather than changing
formatting and error presentation for every existing caller.
Moving to the new API is an explicit choice to use v4 defaults, with presets
available when you want older settings.
Classic APIs remain supported.
For example, load a configuration with strict field checking, then choose its
output indentation:
Unknown struct fields are ignored by default;
WithKnownFields()opts intorejecting them.
Duplicate mapping keys are rejected by default.
Options apply in order, so later options override earlier settings.
Defaults and compatibility
Quoting still depends on scalar content and styles, and line width is a
preference rather than a guaranteed maximum.
NewDecoderuses v3 error formatting;NewEncoderretains v3 output settingswith v4 error formatting.
Choose
WithV3Defaults()to select compatibility defaults through the new API.When replacing
Marshal, also disable wrapping to match its line-width setting:Presets select defaults; they do not reverse every v4 bug fix or reproduce every
legacy code path.
For example, package-level
Loadrequires exactly one document, whereasUnmarshalretains legacy handling of empty input and trailing content.WithSingleDocument()deliberately skips validation of later documents.Use
WithAllDocuments()to load or dump slices as document streams, or use astreaming loader or dumper to process documents individually.
Options, plugins, and nodes
Options control indentation, sequence layout, quoting, document markers,
Unicode escaping, field validation, and more.
OptsYAMLaccepts YAML configuration for supported settings, which can also beshared with the CLI.
The public plugin APIs cover six areas:
merge algorithm.
dotted paths, or reject alias references.
The core module provides implementations for these APIs.
Additional parsers live in separate modules, keeping their dependencies optional.
Existing depth and alias protections remain enabled by default.
yaml.Nodegives access to tags, styles, comments, anchors, and source positions.Node.LoadandNode.Dumpaccept options for node conversion.Pass construction options explicitly inside custom unmarshaler hooks;
Node.Loadstarts with fresh defaults independently of its calling loader.Stream nodes can expose encoding and YAML directives.
Node output retains supported styles and comments without promising identical
source formatting.
Migration details to check
NewLoaderandNewDumperreturn errors; check them before using the stream.Check dumper
DumpandCloseerrors as well.Custom
UnmarshalYAML(*yaml.Node) errorhooks must use the v4 node type.Recognized v3 node hooks produce a migration error rather than silently losing
custom behavior.
The legacy
UnmarshalYAML(func(any) error) errorcallback remains supported.Conversion failures return structured
*yaml.LoadErrorsvalues.Use
errors.Asto inspect structured errors or match legacy*yaml.TypeErrorvalues, rather than relying on a direct type assertion or fixed message text.
Review the migration guide
for the complete compatibility guidance.
Inspect YAML with the CLI
Install the CLI from this release:
Convert to JSON, inspect nodes, or examine scanner and parser output:
The CLI also supports reusable options files and pipelines between intermediate
stages, making small bug reports easier to reproduce.
Runtime plugin selection chooses implementations already linked into the binary.
Further reading and thanks
See the options guide,
plugin guide,
CLI guide,
and API reference.
Please report problems with minimal input, a reproducer, and your Go version in
the issue tracker.
Release-candidate users should update to v4.0.0 and rerun their tests, as some APIs
changed during prerelease development.
Thanks to everyone who tested, reported problems, and contributed to this release.
This discussion was created from the release go-yaml v4.0.0.
All reactions