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:
go get go.yaml.in/yaml/v4@v4.0.0
Use this import path in your Go code:
import"go.yaml.in/yaml/v4"
For an existing v3 application, start by updating imports, reviewing custom
unmarshalers, and running your tests.
You can continue using Unmarshal, Marshal, NewDecoder, and NewEncoder.
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 Load and Dump functions and streaming Loader and Dumper accept
functional 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 into
rejecting them.
Duplicate mapping keys are rejected by default.
Options apply in order, so later options override earlier settings.
Defaults and compatibility
Setting
Classic Marshal / Unmarshal
Load / Dump defaults
Output indentation
4 spaces
2 spaces
Sequence indentation
Non-compact
Compact
Quote preference
Legacy mixed quoting
Single quotes where possible
Preferred output width
Unlimited for Marshal
80 characters
Error presentation
v3 style
v4 style with stage and position
Quoting still depends on scalar content and styles, and line width is a
preference rather than a guaranteed maximum. NewDecoder uses v3 error formatting; NewEncoder retains v3 output settings
with 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 Load requires exactly one document, whereas Unmarshal retains 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 a
streaming 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. OptsYAML accepts YAML configuration for supported settings, which can also be
shared with the CLI.
The public plugin APIs cover six areas:
Loader-Limits: configure depth and alias expansion checks.
Merge-Key: control merge directives and mapping conflicts, or replace the
merge algorithm.
Alias-Data: supply external anchors, retain anchors across documents, use
dotted paths, or reject alias references.
Error-format: select error presentation or implement a custom formatter.
YAML-parser: select an alternative parser implementation.
Tab-indent: opt into tab-aware input and output indentation.
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.Node gives access to tags, styles, comments, anchors, and source positions. Node.Load and Node.Dump accept options for node conversion.
Pass construction options explicitly inside custom unmarshaler hooks; Node.Load starts 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
NewLoader and NewDumper return errors; check them before using the stream.
Check dumper Dump and Close errors as well.
Custom UnmarshalYAML(*yaml.Node) error hooks 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) error callback remains supported.
Conversion failures return structured *yaml.LoadErrors values.
Use errors.As to inspect structured errors or match legacy *yaml.TypeError
values, 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:
go install go.yaml.in/yaml/v4/cmd/go-yaml@v4.0.0
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.
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 PR contains the following updates:
| Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) |
|---|---|---|---|
| [go.yaml.in/yaml/v3](https://github.com/yaml/go-yaml) | `v3.0.5` → `v4.0.0` |  |  |
---
### Release Notes
<details>
<summary>yaml/go-yaml (go.yaml.in/yaml/v3)</summary>
### [`v4.0.0`](https://github.com/yaml/go-yaml/releases/tag/v4.0.0): go-yaml v4.0.0
[Compare Source](https://github.com/yaml/go-yaml/compare/v3.0.6...v4.0.0)
### 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:
```bash
go get go.yaml.in/yaml/v4@v4.0.0
```
Use this import path in your Go code:
```go
import "go.yaml.in/yaml/v4"
```
For an existing v3 application, start by updating imports, reviewing custom
unmarshalers, and running your tests.
You can continue using `Unmarshal`, `Marshal`, `NewDecoder`, and `NewEncoder`.
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 `Load` and `Dump` functions and streaming `Loader` and `Dumper` accept
functional 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:
```go
package main
import (
"fmt"
"log"
"go.yaml.in/yaml/v4"
)
func main() {
var config struct {
Name string `yaml:"name"`
Port int `yaml:"port"`
}
input := []byte("name: api\nport: 8080\n")
if err := yaml.Load(input, &config, yaml.WithKnownFields()); err != nil {
log.Fatal(err)
}
output, err := yaml.Dump(config, yaml.WithIndent(4))
if err != nil {
log.Fatal(err)
}
fmt.Print(string(output))
}
```
Unknown struct fields are ignored by default; `WithKnownFields()` opts into
rejecting them.
Duplicate mapping keys are rejected by default.
Options apply in order, so later options override earlier settings.
#### Defaults and compatibility
| Setting | Classic Marshal / Unmarshal | Load / Dump defaults |
| ---------------------- | --------------------------- | -------------------------------- |
| Output indentation | 4 spaces | 2 spaces |
| Sequence indentation | Non-compact | Compact |
| Quote preference | Legacy mixed quoting | Single quotes where possible |
| Preferred output width | Unlimited for Marshal | 80 characters |
| Error presentation | v3 style | v4 style with stage and position |
Quoting still depends on scalar content and styles, and line width is a
preference rather than a guaranteed maximum.
`NewDecoder` uses v3 error formatting; `NewEncoder` retains v3 output settings
with 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:
```go
output, err := yaml.Dump(config,
yaml.WithV3Defaults(),
yaml.WithLineWidth(-1),
)
```
Presets select defaults; they do not reverse every v4 bug fix or reproduce every
legacy code path.
For example, package-level `Load` requires exactly one document, whereas
`Unmarshal` retains 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 a
streaming 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.
`OptsYAML` accepts YAML configuration for supported settings, which can also be
shared with the CLI.
The public plugin APIs cover six areas:
- **Loader-Limits:** configure depth and alias expansion checks.
- **Merge-Key:** control merge directives and mapping conflicts, or replace the
merge algorithm.
- **Alias-Data:** supply external anchors, retain anchors across documents, use
dotted paths, or reject alias references.
- **Error-format:** select error presentation or implement a custom formatter.
- **YAML-parser:** select an alternative parser implementation.
- **Tab-indent:** opt into tab-aware input and output indentation.
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.Node` gives access to tags, styles, comments, anchors, and source positions.
`Node.Load` and `Node.Dump` accept options for node conversion.
Pass construction options explicitly inside custom unmarshaler hooks;
`Node.Load` starts 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
`NewLoader` and `NewDumper` return errors; check them before using the stream.
Check dumper `Dump` and `Close` errors as well.
Custom `UnmarshalYAML(*yaml.Node) error` hooks 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) error` callback remains supported.
Conversion failures return structured `*yaml.LoadErrors` values.
Use `errors.As` to inspect structured errors or match legacy `*yaml.TypeError`
values, rather than relying on a direct type assertion or fixed message text.
Review the [migration guide](https://github.com/yaml/go-yaml/blob/v4.0.0/docs/v3-to-v4-migration.md)
for the complete compatibility guidance.
#### Inspect YAML with the CLI
Install the CLI from this release:
```bash
go install go.yaml.in/yaml/v4/cmd/go-yaml@v4.0.0
```
Convert to JSON, inspect nodes, or examine scanner and parser output:
```bash
go-yaml -J config.yaml
go-yaml -N config.yaml
go-yaml -T config.yaml
go-yaml -E config.yaml
```
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](https://github.com/yaml/go-yaml/blob/v4.0.0/docs/options.md),
[plugin guide](https://github.com/yaml/go-yaml/blob/v4.0.0/docs/plugin.md),
[CLI guide](https://github.com/yaml/go-yaml/blob/v4.0.0/cmd/go-yaml/README.md),
and [API reference](https://pkg.go.dev/go.yaml.in/yaml/v4@v4.0.0).
Please report problems with minimal input, a reproducer, and your Go version in
[the issue tracker](https://github.com/yaml/go-yaml/issues).
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.
### [`v3.0.6`](https://github.com/yaml/go-yaml/compare/v3.0.5...v3.0.6)
[Compare Source](https://github.com/yaml/go-yaml/compare/v3.0.5...v3.0.6)
</details>
---
### Configuration
📅 **Schedule**: (UTC)
- Branch creation
- At any time (no schedule defined)
- Automerge
- At any time (no schedule defined)
🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.
♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 **Ignore**: Close this PR and you won't be reminded about this update again.
---
- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box
---
This PR has been generated by [Mend Renovate CLI](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0NC4yMTAuMCIsInVwZGF0ZWRJblZlciI6IjQ0LjIxMC4wIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6W119-->
Nicht übernommen: go.yaml.in/yaml/v4 ist ein eigenes Modul, das von keinem Paket hier importiert wird. Das Update fügt nur eine ungenutzte indirekte Abhängigkeit hinzu, die go mod tidy wieder entfernt. yaml/v3 bleibt (über viper) und ist mit #23 auf v3.0.6.
Nicht übernommen: go.yaml.in/yaml/v4 ist ein eigenes Modul, das von keinem Paket hier importiert wird. Das Update fügt nur eine ungenutzte indirekte Abhängigkeit hinzu, die `go mod tidy` wieder entfernt. yaml/v3 bleibt (über viper) und ist mit #23 auf v3.0.6.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
This PR contains the following updates:
v3.0.5→v4.0.0Release Notes
yaml/go-yaml (go.yaml.in/yaml/v3)
v4.0.0: go-yaml v4.0.0Compare Source
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.
v3.0.6Compare Source
Configuration
📅 Schedule: (UTC)
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
This PR has been generated by Mend Renovate CLI.
Nicht übernommen: go.yaml.in/yaml/v4 ist ein eigenes Modul, das von keinem Paket hier importiert wird. Das Update fügt nur eine ungenutzte indirekte Abhängigkeit hinzu, die
go mod tidywieder entfernt. yaml/v3 bleibt (über viper) und ist mit #23 auf v3.0.6.Pull request closed