Changes which may break some users are marked below with: ⚠️

Language

As a reminder, we have two ongoing language experiments since v0.15; a replacement for struct embedding and a rework of aliases. Please give these a try and report any issues or feedback!

⚠️ else is now part of the try experiment

v0.16.0-alpha.2 introduced the else comprehension clause, available to any module targetting language version v0.16.0 or later without needing to use an experiment.

Thanks to user feedback and design discussions, we have come to realize that the existing design needed tweaking. for comprehensions now use a fallback token rather than else in order to clarify intent, and we have also restricted the use of else in chains of comprehension clauses, which could easily cause confusion.

Given how late in the release cycle we already are, and understanding that we probably will want to make further tweaks to this feature before it's stable, we have decided to put this language feature behind a file experiment after all.

Rather than adding @experiment(else), we have chosen to bundle this with @experiment(try), given that try without else does not make much sense.

For more information on the up-to-date else and fallback clauses, follow our how-to guide, or read the updated spec change patch.

Evaluator

Fix a regression introduced by v0.16.0-alpha.2 where cue cmd could suddenly report undefined or missing fields from data in non-tool CUE files.

cmd/cue

cue exp writefs gains an encoding optional field for regular files, to specify an encoding rather than infer it from the filename extension.

Changes which may break some users are marked below with: ⚠️

Language

As a reminder, we have two ongoing language experiments since v0.15; a replacement for struct embedding and a rework of aliases. Please give these a try and report any issues or feedback!

The new try experiment

This experiment adds a try clause in comprehensions as well as the use of ? in field selectors. This addition to the language intends to provide a more concise syntax for handling optional fields without the risk of unintentionally swallowing errors.

You can try this experiment by following our how-to guide. For more information, see the proposal on GitHub and the spec change patch.

The new else comprehension clause

This change adds an optional else clause for CUE modules targetting the language version v0.16.0 or later. With this addition to the language, an if or for comprehension may be followed by an else clause which triggers when the comprehension produces zero values.

Note that this feature is not an experiment; it is available to any CUE module targetting the language version v0.16.0 or later.

You can try this feature by following our how-to guide. For more information, see the full patch which includes the changes to the spec, or read the pre-release version of the language spec.

Evaluator

A number of changes were made to improve support for using cue.Values concurrently; see Issue #2733 for more details and ongoing progress.

A number of panics and other bugs in the evaluator which were reported since v0.15.0 have been fixed; thank you to all who reported these.

cmd/cue

The global --verbose and --trace flags have been moved to the cue get go and cue trim commands respectively, as they were the only ones actually using those flags, and this could be confusing to users.

Fix a bug where loading ./...:pkgname could lead to loading directories with zero CUE files as instances, which could cause poor performance for CUE packages with multiple parent directories.

LSP server

Code Actions: two code actions are now provided, Add surrounding struct braces and Remove surrounding struct braces, which convert between

a: b: c

and

a: {
	b: c
}

with the cursor on b.

Initial LSP support for editing embedded JSON files. This feature provides completions and hover-docs when editing JSON files which are embedded into CUE via the @embed attribute. A teaser video is available on YouTube. Support for embedded YAML files will appear soon.

Several bug fixes, including better behaviour for files and directories with spaces; improvements for value aliases (foo: L=x); LSP rename now provides placeholder text.

See our Getting Started wiki page for instructions on how to set it up with your editor.

Please report any bugs or missing features you encounter via the Issue tracker or via the #lsp channels on Discord or Slack.

Encodings

Add support for encoding YAML tags like key: !Custom value by using CUE attributes like key: "value" @yaml(,tag="!Custom").

Standard library

The net package adds CompareIP to compare two IP addresses, which can be useful for computing with IP ranges.

The net/http package adds Serve as an experimental API to listen on a port and serve HTTP requests.

The tool/file package adds Symlink to create symbolic links.

Go API

cue/ast gains the NewPredeclared and Ident.IsPredeclared to mark and detect identifiers referencing predeclared names like error or int rather than fields which may shadow those names in the current scope.

⚠️ cue/token.Compare now sorts absolute paths before relative ones, to ensure consistent behavior between Unix-like systems and Windows.

⚠️ The long-deprecated and hidden cue.Instance.Eval method is now removed.

Changes which may break some users are marked below with: ⚠️

Language

As a reminder, we have two ongoing language experiments since v0.15; a replacement for struct embedding and a rework of aliases. Please give these a try and report any issues or feedback!

⚠️ The cmdreferencepkg global experiment is now stable, meaning that CUE_EXPERIMENT=cmdreferencepkg is always enabled.

#"""# is now accepted as a string literal quoting a double quote, ".

Multiline string literals now require a trailing newline, matching the language spec.

Evaluator

Performance

Further improve the use of caching in the typochecker algorithm; this provides speed-ups of up to 80% on some large projects.

Very large structs (tested with 20,000 fields) are up to 80% faster now, as we were repeating some work unnecessarily.

A great deal of effort has gone into reducing the allocations and memory usage across a number of projects. For some of these, memory usage is down by as much as 60%.

These improvements were possible thanks to our Unity service, letting us analyze CUE's performance and test for regressions on third party projects. Contact @mvdan on Discord, Slack, or via the Unity page to ensure that your project is included or you are running into slowness.

Other changes

Fix a regression introduced in v0.13 where the or built-in with literal arguments could stop behaving like a disjunction.

A number of panics and other bugs in the evaluator which were reported since v0.15.0 have been fixed; thank you to all who reported these.

cmd/cue

Add support for $DOCKER_AUTH_CONFIG to directly provide the contents of $DOCKER_CONFIG/config.json to authenticate with module registries, matching Docker's current behavior.

The --outfile flag now works when given non-regular files such as named pipes or sockets.

⚠️ cue mod publish no longer ignores sub-directories containing a go.mod file as if they were nested CUE modules; those are already skipped based on the presence of cue.mod.

⚠️ Using cue inside the cue.mod directory now fails consistently with a clear error message to not place CUE code there. Previously, some commands worked while others failed with confusing errors.

LSP server

Completions: a complete overhaul of how the LSP server suggests code completions. This solves the previous naïve implementation which would only make suggestions after a field name or path had been started. Now completions are available from within whitespace.

Embedded paths with mutual dependencies: embedded paths with multiple components (e.g. a.b.c) can in some cases only be fully resolved after the resolution of other embedded paths. The LSP server can now correctly handle these dependencies.

Document Symbols: the CUE LSP server now implements LSP "Document Symbols" functionality. This is often used by editors to provide light-weight breadcrumb navigation within a file.

Diagnostics: some preliminary diagnostics are now sent from the LSP server back to the editor. Initially this mainly indicates syntax errors in CUE files, but this can be extended in the future.

Bug fixes: many smaller bug fixes, addressing issues around imports, path resolution, formatting of standalone CUE files, amongst others.

See our Getting Started wiki page for instructions on how to set it up with your editor.

Please report any bugs or missing features you encounter via the Issue tracker or via the #lsp channels on Discord or Slack.

Encodings

cue get go now detects which Go packages use Kubernetes type semantics via // +k8s:openapi-gen=true and obeys the field annotations // +optional and // +nullable.

cue get go gains a --codec flag to configure the use and priority of Go struct field tags like json or yaml.

Fix a bug where cue get go could skip over fields whose type implements one of the supported marshaling interfaces.

Fix a few bugs where cue get go could result in invalid or failing CUE code.

JSON Schema's Config.OpenOnlyWhenExplicit option is now exposed for the CLI via the filetype tag jsonschema+openOnlyWhenExplicit.

JSON Schema now properly encodes hash references for better compatibility with other tools.

Standard library

The strconv package adds ParseNumber, like ParseInt or ParseFloat but allowing other CUE number strings such as 1Ki.

The net package adds InCIDR to test whether an IP is contained by a CIDR string.

The net package adds ParseCIDR to extract useful information from a CIDR string.

Go API

cue.Value.Decode now supports the new cue.Unmarshaler interface, allowing Go types to implement their own CUE value decoding logic via an UnmarshalCUE(cue.Value) error method.

The new cue.IsIncomplete function reports whether the given value is a CUE incomplete error.

⚠️ cue.Value.Decode now uses cue.IsIncomplete to not treat incomplete errors as fatal, allowing the decoding to continue.

Fix a bug where cue.Value.Decode could behave incorrectly when decoding a CUE null or incomplete value.

⚠️ The long-deprecated cue/ast.Node.Comments and cue/ast.Node.AddComment interface methods are now removed; use cue/ast.Comments and cue/ast.AddComment respectively.

⚠️ The long-deprecated and unused cue/parser.FromVersion and cue/parser.DeprecationError APIs are now removed.

Evaluator

Fix a panic which could occur when using the error built-in with cyclic references.

Fix a panic which could occur when loading @experiment(aliasv2) syntax with an invalid alias name.

cmd/cue

Relax the cue login --token validation to allow future Central Registry token types.

Encodings

Fix a bug in the TOML decoder where nested arrays were causing incorrect "duplicate key" errors.

Evaluator

Fix a panic which could occur when using Expr after LookupPath on a cue.Value.

cmd/cue

Fix a panic which could occur when using cue cmd tasks referencing definitions.

Fix a panic which could occur when cue get go encountered a Go enum type with zero named values.

Encodings

Fix a bug in the TOML decoder where nested arrays were not being correctly mapped to CUE values.

Evaluator

Fix an evalv3 regression first introduced in v0.11.0 where the and built-in function started evaluating its arguments too eagerly, causing failures in cue def.

Fix an evalv3 regression where closedness info could be lost when using a comprehension.

Fix a bug where the evaluator would panic on alias cycles with dynamic fields rather than giving a good error.

LSP

Formatting standalone CUE files - either without a package name, or outside of a CUE module - now works correctly.

Fix a bug where trying to use "find references" on a CUE module with nested modules would cause a hang.

Fix a bug where resolving path roots did not work correctly in the presence of struct embeddings.

cmd/cue

Fix a regression in v0.15.0 where cue get go no longer skipped generating CUE files without any declarations.

Go API

Fix a bug in the subsume package where a struct with a pattern constraint did not subsume a closed struct with a matching field.

Rename the bootstrap build tag used in the internal/filetypes package to cuebootstrap to avoid conflicts with build tags in other Go modules.

Changes which may break some users are marked below with: ⚠️

Note that this release no longer includes a checksums.txt asset; GitHub now provide digests natively.

LSP

This release includes the initial version of cue lsp - with support for "go to definition", "find references", rename, code completion, hover documentation, and code formatting.

See our Getting Started wiki page for instructions on how to set it up with your editor.

Please report any bugs or missing features you encounter via the Issue tracker or via the #lsp channels on Discord or Slack.

Language

explicitopen experiment for #A...

The explicitopen per-file experiment enables the posfix ... operator to explicitly open closed structs, allowing additional fields to be added. This change simplifies CUE's semantics, reduces user confusion, and enables clearer expression of type extensibility patterns.

You can try this experiment by following our how-to guide. For more information, see the proposal on GitHub and the spec change patch.

aliasv2 experiment

The aliasv2 per-file experiment implements the new "postfix aliases" syntax, and introduces a "self" predeclared identifier referring to the innermost surrounding struct or list.

You can try this experiment by following our how-to guide. For more information, see the proposal on GitHub and the spec change patch.

Other experiments

⚠️ With its proposal accepted, the keepvalidators global experiment is now stable, meaning that CUE_EXPERIMENT=keepvalidators is always enabled.

With its proposal accepted, the structcmp per-file experiment is now stable with language.version at v0.15.0 or later, meaning that the @experiment(structcmp) attribute is unnecessary as it's always enabled.

Evaluator

⚠️ Removing evalv2

The old evalv2 evaluator, which previously could be re-enabled via CUE_EXPERIMENT=evalv3=0, is now deleted. The new evalv3 evaluator has been on by default since v0.13.0, and at this point our entire test suite including Unity is working.

Removing the old evaluator reduces significant load on development, as we were able to clear out 4000 lines of code, and simplify the internal types and code structure. This is a necessary step to unblock ongoing feature and performance work in the evaluator.

As a bonus, because the old and new evaluators shared many core evaluator types, removing the fields only used by the old evaluator yields modest memory usage improvements of around 4-6%.

Performance

Evaluating concrete CUE values no longer involves dependency analysis; this should result in modest speed improvements when marshaling to YAML, via either cue export -e expr -o yaml or yaml.Marshal.

Dependency analysis now avoids computing references more than once, which resolves an expontential performance issue for some configurations using chains of CUE references.

Add caching to a part of the typochecker algorithm; this has been measured to provide performance improvements of up to 30% on a few large projects.

cue/parser now reuses more memory, which results in parsing performance improvements of up to 30% and memory savings of up to 50%, especially when loading large CUE data files.

Other changes

File embedding via the @embed attribute has gained an allowEmptyGlob option, to allow glob patterns to match zero files without causing an error.

The evaluator now shows all user errors created with the error builtin when they can be related to a disjunction failure. Previously, the evaluator would try to only show user errors directly part of a disjunction error, but that caused too many omissions.

Some error positions which were lost in the transition from evalv2 to evalv3 have been reintroduced.

Fix a bug where required fields in a definition might not be enforced when unifying with an inline struct in an expression, such as (#RequiresFoo & {bar: "baz"}).bar.

Fix a regression introduced in v0.12.0 where incomplete errors were not being handled consistently if they directly involved the top-level value.

A number of panics and error regressions in the evaluator which were reported since v0.14 have been fixed; thank you to all who reported these.

cmd/cue

A new cue help experiments command is introduced to document all available per-file and global experiments.

The cue fix --exp flag is introduced to rewrite files or packages to use new and experimental semantics with @experiment attributes.

cue mod mirror now copies OCI referrers between registries, which ensures that artifacts like signatures and attestations which reference modules being mirrored are copied as well.

cue mod resolve gains a --deps flag that lists all dependencies of the current module and which registries they resolve to.

cue get go gains an --outfile flag to generate exactly one CUE file for a single Go package, which can be useful when integrating cue get go into build systems like Bazel.

Fix a regression introduced in v0.9.0 where loading a qualified pattern like ./...:pkgname no longer filtered files based on the package name given.

cue get go now stops on any Go package loading error. Trying to continue in the presence of syntax or type-checking errors could lead to generating incorrect CUE.

Encodings

Initial support for encoding CUE schemas as JSON Schema is added. This includes a new encoding/jsonschema.Generate Go API, as well as CLI support via cue def --out jsonschema. This is currently very experimental, and many features are missing. For now, it can only generate a single version of JSON Schema, draft/2020-12.

The YAML library in the archived Go module gopkg.in/yaml.v3 has been replaced by go.yaml.in/yaml/v3, an active fork now maintained by the YAML organization.

cue exp gengotypes is improved to handle more edge cases with CUE package imports which could result in broken Go code.

The Protobuf decoder has been tweaked to not require files such as google/protobuf/timestamp.proto to exist on disk, given that they are mapped to CUE standard library APIs directly.

The Protobuf decoder has also been tweaked to support fully qualified references such as my.pkg.name.MessageName.

A bug is fixed in the TOML decoder where sub-table keys could incorrectly lead to duplicate key errors.

Standard library

The net package has gained new AddIP and AddIPCIDR functions to add numerical offsets to IP addresses or CIDR networks.

The Atoi, ParseInt, and ParseUint functions in the strconv package now work on integers with unlimited precision, like the rest of the CUE evaluator, rather than just a maximum of 64 bits.

Go API

The new cue.Value.IsClosed and cue.Value.IsClosedRecursively methods report whether a value has been closed at the top level or recursively, which is useful information when writing schema encodings.

The new cue.Patterns and cue.Selector.Pattern APIs allow introspecting pattern constraints in CUE struct values.

The new encoding/yaml.Decoder API allows decoding a stream of YAML documents, given that existing APIs did not support streams of multiple YAML documents.

encoding/json gains JSON Pointer APIs, which are already useful in packages like encoding/jsonschema.

cue/ast introduces PostfixExpr to support upcoming additions to the language syntax.

cue/ast introduces StringLabelNeedsQuoting to determine whether a string label needs to be quoted when used in CUE syntax.

cue/ast introduces NewStringLabel to create an ast.Label as either an unquoted identifier or a quoted string, depending on whether the string label needs quoting.

tools/fix has gained new APIs to fix configs to use an active experiment, as well as fixing configs to a newer language version.

cue introduces a Path.Append convenience method.

⚠️ cue/build.Instance.Match is removed, given that it was never set to any value at any point since it was added.

cue/token is adjusted so that node positions within a file never result in an offset which is outside the bounds of the file. This could easily lead to subtle bugs or panics when using node position offsets.

⚠️ The [cue/token.Pos.Before](https://pkg.go.dev/cuelang.o...

Changes which may break some users are marked below with: ⚠️

Note that this release no longer includes a checksums.txt asset; GitHub now provide digests natively.

cmd/cue

cue mod resolve gains a --deps flag that lists all dependencies of the current module and which registries they resolve to.

LSP

The LSP now supports finding references to a declared name, which can be thought of as the opposite of "go to definition". Using the same underlying mechanism, the LSP now also supports the "rename" operation.

A number of bugs have been fixed, such as package imports not working in standalone files when inside a valid CUE module.

Go API

The new encoding/yaml.Decoder API allows decoding a stream of YAML documents, given that existing APIs did not support streams of multiple YAML documents.

⚠️ The cue/token.Pos.Before method is now rewritten to match cue/token.Pos.Compare, given that it always returned "false" for positions from different files. The method is now deprecated as well.

Changes which may break some users are marked below with: ⚠️

Note that this release no longer includes a checksums.txt asset; GitHub now provide digests natively.

Evaluator

aliasv2 experiment

⚠️ The self experiment introduced in v0.15.0-alpha.2 has been renamed to aliasv2, to fully implement the Postfix Aliases proposal on GitHub.

Adding a new experiment like @experiment(postfixalias) alongside @experiment(self) was not a good option given that cue fix can only adjust existing code correctly when both experiments are enabled. Allowing the use of just one half of the experiment would add too many tricky edge cases.

Once a module's language.version targets v0.15.0, this can be enabled via the file attribute @experiment(aliasv2). You can use cue fix --exp=aliasv2 to transition existing CUE code in a module to the new alias syntax and semantics.

Other changes

Fix a bug where required fields in a definition might not be enforced when unifying with an inline struct in an expression, such as (#RequiresFoo & {bar: "baz"}).bar.

Fix a bug where a value's reference to self through a let declaration would hang the evaluator.

Add caching to a part of the typochecker algorithm; this has been measured to provide speed-ups of up to 30% on a few large projects.

cmd/cue

cue mod mirror now copies OCI referrers between registries, which ensures that artifacts like signatures and attestations which reference modules being mirrored are copied as well.

cue get go gains an --outfile flag to generate exactly one CUE file for a single Go package, which can be useful when integrating cue get go into build systems like Bazel.

Encodings

Initial support for encoding CUE schemas as JSON Schema is added. This includes a new encoding/jsonschema.Generate Go API, as well as CLI support via cue def --out jsonschema. This is very experimental as yet, and many features are missing. For now, it can only generate a single version of JSON Schema (draft/2020-12).

The YAML encoder no longer uses CUE's dependency analysis algorithm. This helps prevent panics that some users had run into with cue export -e expr --out yaml.

Go API

The new cue.Value.IsClosed and cue.Value.IsClosedRecursively methods report whether a value has been closed at the top level or recursively, which is useful information when writing schema encodings.

The new cue.Patterns and cue.Selector.Pattern APIs allow introspecting pattern constraints in CUE struct values.

Evaluator

Fix an unintended evalv2 regression in v0.14.1; the change only intended to affect evalv3.

Fix a panic in the parser which could occur when @experiment() file attributes are invalid.

Fix an edge case where binary streams with ''' sequences would not roundtrip correctly.