--- title: "Changelog" url: https://recursiveai.org/oneyaml/go/docs/changelog/ description: "All notable changes are listed here, newest first. The format follows Keep a Changelog, and versions follow Semantic Versioning. Breaking changes are…" version: "1.0.0" source: https://github.com/recursive-ai-oss/oneyaml-go/blob/7a4c8e39f041b945ee5f121c055f03bc2d7d01d9/CHANGELOG.md --- # Changelog All notable changes are listed here, newest first. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/). 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 major version has a new module path (`oneyaml.dev/go/v2`), and the entry says so. What a release promises, and the supported Go versions, are under [Stability](https://recursiveai.org/oneyaml/go/docs/overview/#stability). ## [Unreleased] ## [1.0.0] - 2026-10-16 The first stable release. From 1.0.0 the API is stable under the promise in [Stability](https://recursiveai.org/oneyaml/go/docs/overview/#stability). ### Breaking - `LimitError.Limit` is now of the new type `Limit` and names the `LimitSet` field of the bound (`LimitMaxDepth`, `LimitMaxAliasNodes` and so on). It used to be free text such as `"depth"`, `"alias expansion nodes"` or `"patch output size"`. The text is now in the new field `What`. Patch limits report the field that governs them: `MaxInputBytes` for the patch text and for the document a patch makes, and `MaxAliasBytes` for the text a patch copies. **Migrate:** compare `le.Limit` with the `Limit` constants, or match a sentinel such as `errors.Is(err, oneyaml.ErrMaxDepth)`, and read `le.What` where you printed `le.Limit`. - `LimitError.Option` now has one form, `Limits (MaxDepth)`, which names the option and the `LimitSet` field that raise the bound. It used to be `Limits`, `Limits or NoLimits`, `Limits (MaxAliasNodes)` or `none: split the stream`, depending on where the limit was hit. It is empty for the three bounds no option changes: the nesting of a patch value (10,000 levels), the nesting of typed Go values (100,000 levels) and the 2 GiB size of a `Document`. It is also always empty in `compat/yamlv3` and `compat/k8syaml`, which take no limit options and sometimes suggested one. **Migrate:** switch on `le.Limit` rather than reading `Option`. - `SyntaxError.Category` is now of the new type `Category`, and `CategorySyntax`, `CategoryEncoding` and `CategoryDuplicateKey` are typed constants. They used to be untyped strings. Comparisons, `switch` statements and printing still compile. **Migrate:** where you store a category in a `string` or pass it as one, write `string(se.Category)`. - `TypeError.GoType` is now a `reflect.Type`. It used to be a `string`. It is nil when no type was involved, so two types with one name in different packages can be told apart and a type can be compared: `te.GoType == reflect.TypeFor[time.Duration]()`. Messages print the type as before. **Migrate:** where you used the string, call `te.GoType.String()` after checking for nil. - `KnownFields`, `MergeKeys` and `YAML11Strings` are now `func(...bool) Option`, and `Document.Get`, `Document.Decode` and `Node.Decode` now take `...Option` (see Added). Every call that compiled before still compiles. A method value or a function-typed variable no longer matches, such as `var f func(string, any) error = doc.Get`, and neither does an interface that lists the old methods. **Migrate:** wrap the call in a function literal, such as `func(p string, v any) error { return doc.Get(p, v) }`. - `Node.Find` now returns an error matching `ErrAmbiguousKey` for a key written more than once in its mapping, and `Node.Lookup` now returns `false` for it. Both used to return the first entry. `Document.Get` and every edit already refused a pointer through such a key. **Migrate:** read every entry with `Entries`, and use `Find` to learn why a lookup failed ([Reading while you edit](https://recursiveai.org/oneyaml/go/docs/editing/#reading-while-you-edit)). - Under a `MaxInputBytes` bound (`Untrusted()` sets one), `Set`, `Rename`, `SetHeadComment` and `SetLineComment` now refuse an edit that would make the text longer than the bound. Before, only `ApplyPatch` and `ApplyMergePatch` were held to it. The error is an `*EditError`, and `errors.As` finds the `*LimitError` inside it. The document is unchanged, and an edit that makes the text shorter is always allowed. For a UTF-16 or UTF-32 document, these edits and the patches now count the size in the encoding the document is written in, byte order mark included; patches used to count the UTF-8 size. Even with no bound set, an edit or patch is refused when the text would pass 2 GiB, the most a `Document` can address. **Migrate:** pass a larger bound when you parse, with `Limits(oneyaml.LimitSet{MaxInputBytes: n})` after `Untrusted()` ([Limits](https://recursiveai.org/oneyaml/go/docs/limits/#each-limit)). - `Parse`, `Unmarshal`, the `Decoder` and the compat packages now refuse two kinds of invalid YAML with a `*SyntaxError`. Version 0.3.0 loaded both: - Inside a flow collection, a flow collection that touches the `:` of a plain or empty key, as in `{a:{}}`, `[a:[]]` and `{:{0}}`. After a quoted key (`{"a":{}}`) it is still allowed. - A verbatim tag that is neither a local tag nor a URI that starts with a scheme, as in `!`, `!` and `!<$:?>`. **Migrate:** put a space after the colon (`{a: {}}`), and write such a tag as a local tag (`!`), a full URI (`!`) or a shorthand tag (`!name`). - `compat/yamlv3`: `Marshal` now returns an error naming the type and the method for a `MarshalYAML` method that is not `MarshalYAML() (interface{}, error)`. It used to skip the method and write the value field by field, as yaml.v3 does. The `oneyaml` package already refused such a method. **Migrate:** give the method the signature `MarshalYAML() (interface{}, error)`, or remove it. - `compat/yamlv3`: `Marshal` now returns an error naming the type for a value of the `Node` type of `gopkg.in/yaml.v3` or `go.yaml.in/yaml/v3`. This covers such a value given directly, held in a field, or returned by a `MarshalYAML` method. The adapter used to write the node's Go fields (`kind: 8`, `style: 0`, ...), where yaml.v3 writes the YAML the node holds. **Migrate:** build the adapter's own `yaml.Node`, or write that value with yaml.v3 ([Migrating from yaml.v3](https://recursiveai.org/oneyaml/go/docs/migrate-yaml-v3/#check-after-the-swap)). - `compat/yamlv3`: `Unmarshal` and `Decode` now return an error naming the type when the target is the `Node` type of `gopkg.in/yaml.v3` or `go.yaml.in/yaml/v3`, held directly, in a field, in a slice or map, or behind a pointer. They used to return no error and leave the node empty. A null value still leaves a pointer to it nil. **Migrate:** decode into the adapter's `yaml.Node`. ### Added - Sentinel errors for every error kind, so a single `errors.Is` call tells kinds apart. `*SyntaxError` matches `ErrSyntax`, and also `ErrEncoding` or `ErrDuplicateKey` for those categories. `*LimitError` matches `ErrLimit`, and also the sentinel of its limit, named like the `LimitSet` field: `ErrMaxDepth`, `ErrMaxAliasNodes`, `ErrMaxAliasBytes`, `ErrMaxInputBytes`, `ErrMaxScalarBytes`, `ErrMaxDocuments`, `ErrMaxNumberDigits` and `ErrMaxPatchWorkRatio`, also through an `*EditError` that wraps it ([Limits](https://recursiveai.org/oneyaml/go/docs/limits/#each-limit)). - The type `Limit` and its constants `LimitMaxDepth`, `LimitMaxAliasNodes`, `LimitMaxAliasBytes`, `LimitMaxInputBytes`, `LimitMaxScalarBytes`, `LimitMaxDocuments`, `LimitMaxNumberDigits` and `LimitMaxPatchWorkRatio`, for `LimitError.Limit`. Also the field `LimitError.What`, and the type `Category` for `SyntaxError.Category` (see Breaking). - `oneyaml.Pointer(tokens...)` builds an RFC 6901 pointer from keys and indices, escaping `~` and `/` in each. For example, `Pointer("metadata", "labels", "app.kubernetes.io/name")` is `/metadata/labels/app.kubernetes.io~1name`. Use it instead of joining keys with `"/"`. - `Document.Get`, `Document.Decode` and `Node.Decode` take options for one read, applied on top of the options the Document was parsed with. For example, `doc.Get("/spec", &spec, oneyaml.KnownFields())` reads one part strictly. `KnownFields`, `MergeKeys`, `Limits`, `Untrusted` and `NoLimits` apply to a read; other options are ignored. The options also hold for the decodes an `UnmarshalYAML` hook makes during that read. A bound given to a read of a Document replaces the Document's bound in both directions, so `NoLimits()` on a read of a Document parsed with `Untrusted()` lifts its bounds for that read. Pass such options only for input you trust ([Reading values back](https://recursiveai.org/oneyaml/go/docs/editing/#reading-values-back)). Inside an `UnmarshalYAML` hook it is different: options given to `Node.Decode` may only tighten the limits of the read that called the hook, never loosen them. For each bound the stricter of the caller's and the option's applies, so a type's hook cannot undo a caller's `Untrusted()`. `KnownFields` and `MergeKeys` given there apply as given. - `KnownFields`, `MergeKeys` and `YAML11Strings` take an optional bool, so `KnownFields(false)` turns the option off again, and a later option overrides an earlier one. Calls without an argument behave as before. - `Node` is now documented as comparable: two Nodes are equal when they are the same node of the same state of the same Document. A Node read before an edit is never equal to the one read after it. ### Changed - `LimitError.Path` of a limit hit by a decode inside an `UnmarshalYAML` hook is now the pointer in the whole document, like the path of a `*TypeError`. This holds when the hook wraps the error, as with `fmt.Errorf("...: %w", err)` or `errors.Join`, when hooks are nested and each one wraps it, and when an outer hook decoded a child of its `Node`. It used to be empty. The read does not change the error the hook returned: `errors.As` on the read's error finds a copy that carries the whole-document path. A hook may therefore keep that error and return it from later reads, even on several goroutines at once, and those reads return it as it is. - A type error found by a decode inside an `UnmarshalYAML` hook (a `Node.Decode`, or the function a func-style hook is given) is now reported where the value is in the input, with every mismatch the hook's decode found, as for a read without the hook. Its path is the hook's path followed by the path inside the node the hook decoded, so a hook that decodes a child node reports that child's path. Before, only the first mismatch was reported, at the first key of the hooked mapping, and a child's path was cut off at the hook. A bad value on line 7 could be reported on line 5. This holds at any depth of nested hooks and on every read path. - The `Unmarshaler` documentation now says how a `Node` that `UnmarshalYAML` keeps may be used after the method returns: later, from one goroutine at a time, but not from another goroutine at the moment the method returns. A kept Node goes on reading its own subtree, whichever read gave it. One kept from `Unmarshal` reads the byte slice you passed in, so leave that slice unchanged while you keep the Node. One kept from a `Document` read becomes stale when the `Document` is edited. - An error that a hook returns from reading other text, such as an `Unmarshal` of its own input, is now reported at the hook's value with the hook's type as `GoType`. The position and path inside the other text stay in the message: `line 1, column 4: /a: line 8, column 4: /x: ...`. Before, its path was joined onto the hook's (`/a/x`) and its own line and column were lost. - A type whose `UnmarshalYAML` method has a form that cannot be called, and a `Node` used as a decode target, are now collected like a value that does not fit. The value is skipped, the rest of the document is read, and the `*TypeError` lists every mismatch. The first such value used to stop the read. - `LimitError.Path` is now set for limits that are hit at a value while it is read: alias expansion, scalar size, number digits and the fixed nesting bound of typed values. It was already set for patches. It stays empty for the limits `Parse` reports and for input size, document count and nesting that the parser stops at. `LimitError.Error` shortens a `Path` longer than 512 bytes, as `TypeError.Error` does. - Limit error messages name the option in its new form, or none (see Breaking), and give the path when there is one. The document-count limit from `Parse` now says "documents per stream", as the `Decoder`'s does. ### Fixed - An alias refers to the latest anchor of its name written before it, even when that anchor is inside an earlier node with the same anchor name. In `a: &b {s: &b 1, t: *b}`, `t` is `1`. This document used to be refused with "refers to a node that contains it". In `a: &b {se: &b 1}` followed by `copy: *b`, `copy` is `1`; it used to be `{se: 1}`. Every reader agrees, the compat packages included. - An unknown field found under `KnownFields()` by a decode inside an `UnmarshalYAML` hook now matches `ErrUnknownField`. It did not. - Edits to a later document of a stream that starts with a byte order mark: `Set` of a new key and `SetHeadComment` on its first entry or root work, and the mark stays at the start of the line. They used to fail with "edit could not be applied" or `ErrUnsupportedEdit`. - `Set` of the empty value of an explicit key (`? key`) followed by a `: value` line that belongs to an outer mapping writes the value under the key. It used to fail with "edit could not be applied". - `compat/yamlv3` reads comments onto the same nodes as yaml.v3 in more layouts: - A comment on a dash line with no value (`- # note`) goes to the first key or scalar of the item, or to a flow collection that comes first in it. It used to be moved above the item. - The comments of an empty last item (`- # note` at the end of the text) are the document's foot comment. They used to be dropped. - A foot comment of the item before such a dash line stays with that item. It used to be dropped. - A comment line just before the closing bracket of a flow collection is the foot comment of the last item or key. It used to be dropped. - The comments after a flow collection that ends on the first line of the text (`[a, b]` or `a: [1, 2]`, then `# note`) are the document's foot comment. They used to go to the collection, or to its key. - `compat/yamlv3` writes text that reads back: - A folded scalar (`>`) always reads back as the value written. Some values used to read back with a line break turned into a space or an extra line break, such as a line followed by an indented line. In some of these cases yaml.v3's own text does not read back. - A foot comment held by a block collection that is an item of a sequence is written once, after that collection. It used to be dropped. - A blank line between the lines of a head comment is written without indentation, as yaml.v3 writes it. - `compat/yamlv3` reads each comment line once, and tells one line from another by where it stands in the text, not by its words, so two comments with the same words are both kept. When several sequences start on one dash line (`- # a`, then `- # b`, then a mapping), the comment lines above the dashes were given to more than one node, and writing the result repeated them, adding a copy on every round trip. Comments at the end of a document are no longer dropped when the key that would take them has a foot comment already, and a comment block under `key:` followed by a blank line and another block heads the first key of the value, as in yaml.v3. ## [0.3.0] - 2026-10-16 ### Added - `Node.Find(key)` is the checked form of `Lookup`: it returns the value with a `nil` error, or an error that says why there is none. The error matches `ErrNotFound` for an absent key (or a node that is not a mapping), `ErrStaleNode` for a node read before an edit, and `ErrAmbiguousKey` when a merge brings the key in from two places of one source, and it is a `*LimitError` when a merge search was refused by `MaxAliasNodes`. `Lookup` reports all of these as `false`. See [Reading while you edit](https://recursiveai.org/oneyaml/go/docs/editing/#reading-while-you-edit). - `Node.Err` says why a `Node` reads as zero values: it is `nil` for a node you can read, matches `ErrStaleNode` when the document was edited after the node was read, and matches `ErrNotFound` for the zero `Node`, such as the one a failed `Lookup` returns. `Value` of a stale node is `""`, the same as an empty scalar, so `Err` is the check to make. See [Reading while you edit](https://recursiveai.org/oneyaml/go/docs/editing/#reading-while-you-edit). - With `MergeKeys()`, a pointer also finds the keys a `<<` merge brings into a mapping, with the precedence decoding gives them: `Document.Get`, the patch `test` operation, the `from` of a patch `copy`, `Node.Lookup` and `Node.Find` read them. A `copy` from such a key copies the merged value and leaves the merge source unchanged. `Set` on such a key adds an explicit key that overrides the merged one. Each merge source is searched once, and the keys read count against `MaxAliasNodes`. See [Merge keys](https://recursiveai.org/oneyaml/go/docs/editing/#merge-keys) and the Changed entry below. - `ApplyMergePatch` also reads a merge patch written in YAML, with the same refusals as a YAML `ApplyPatch`. Text that starts with `{` or `[`, or is valid JSON, is still read as JSON. A mapping key that is not a string (`1: 5`, `true: 5`, an empty key) is refused at any depth with its line and column, because merge patch members are named by strings; quote the name to use it. See [Patches written in YAML](https://recursiveai.org/oneyaml/go/docs/patches/#patches-written-in-yaml). ### Changed - **Breaking:** more repeated mapping keys are duplicate-key errors, so some input that used to load is refused: - repeated `.nan` keys, in any spelling (`.nan` and `.NaN` are one key), read into `any`, a `map[float64]T` or another map whose keys are not strings. A map with string keys still compares keys as text; - a repeated key that no field of a struct target has, and a key repeated inside a value the target ignores. `a: 1` twice into a struct with no field `a` used to load; - `compat/yamlv3` reports a key repeated at the top of a mapping its target ignores, as yaml.v3 does. This removes a listed gap. Fix such input by removing the repeated key. The rules are in the [`Unmarshal` reference](https://pkg.go.dev/oneyaml.dev/go#Unmarshal). - **Breaking:** `Parse` refuses a `\u` or `\U` escape that is not a Unicode scalar value, such as a lone surrogate (`"\ud83d"`), a low surrogate before a high one, or a value past `U+10FFFF`, with a `*SyntaxError`. `Parse` used to accept such a document, and only `Get` or `Decode` of the value failed. `Unmarshal` already refused it. Write a valid escape instead: a character outside the Basic Multilingual Plane as an escaped surrogate pair (`"\ud83d\ude00"`), which is now read as one character (see Fixed), or as `\U0001F600`. A lone surrogate is not a character, so replace it, with `\uFFFD` for example, or remove it. - **Breaking:** with `MergeKeys()`, an edit that would change a key only a merge source has is refused with `ErrAliasWrite`, because it would write into the source through an alias: `Remove`, the patch operations `remove`, `replace` and `move`, a merge patch member `null` that would delete it, and any write below such a key or through the merge key itself (`/use/<