cue-lang/cue v0.17.0

on GitHub

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

Language

The active try experiment renames the new fallback keyword, used with for comprehensions, to otherwise. fallback continues to be accepted for now, but is rewritten to the new form.

The active aliasv2 experiment now allows ~(X) as an alternative to ~X for the single postfix alias form. ~X is also rewritten as ~(X) for the sake of consistency and clarity.

Language versions v0.17.0 and later allow omitting commas in multi-line lists. Just like a newline after a struct field implies a comma, a newline after a list element now implies a comma as well.

Language versions v0.17.0 and later allow a newline or a comma before the closing bracket of an index expression, matching how lists and func arguments allow omitting trailing commas.

The language spec is tweaked to make $ a valid identifier, which was already allowed by the parser and evaluator.

⚠️ Support for the infix div, mod, quo, and rem operators has been removed. Since late 2020, these infix forms have been undocumented and rewritten by cue fix to the new function calls.

The new shortcircuit experiment

This release introduces the shortcircuit experiment, which changes the && and || operators to not evaluate the right operand if the left operand alone determines the result.

This matches the behavior already documented in the CUE spec and is consistent with most mainstream languages, but for the sake of a smooth transition for end users, we are rolling out this change via an experiment.

You can try this experiment via the @experiment(shortcircuit) file attribute. To mimic the old behavior with the experiment, you can use a hidden field:

_y: Y
if X && _y {}

Evaluator

Comprehensions

The comprehension algorithm now waits to run a comprehension's body until the fields it reads have a concrete value, rather than trying to produce its fields up front. This resolves a number of long-standing bugs, most notably the last known regressions from evalv2, where a comprehension that should have resolved instead failed as an incomplete value or a cycle.

This design also greatly simplifies upcoming evaluator work, such as introducing new builtins to replace comparing values to bottom, as well as the design of evalv4.

Other changes

The evaluator no longer deduplicates errors just by position, which was causing some useful errors from disjunctions or standard library calls to be dropped incorrectly.

Several long-standing cycle-detection bugs have been fixed, such as self-referential uses of matchN and matchIf, self-feeding disjunctions, and comprehensions that read a let binding which refers back to the comprehension's own fields.

Fixed a bug where the same package imported via different qualified import paths (e.g. foo.com/bar@v0 or foo.com/bar:baz) did not share the same hidden field namespace.

Resolving an unversioned import from a dependency module now respects that module's own default major version, instead of always using the main module's default.

Fix a number of issues where cue def could produce invalid CUE output, such as due to name conflicts.

Fix an evaluator regression where embedded disjunctions across packages may not correctly apply closedness.

Fix an evaluator bug where cue.Context.BuildExpr of close({}) did not actually result in a closed struct.

Fix a bug where some calls to standard library functions or validators did not include the "error in call to pkg.Func" error context, or included it twice.

A few changes to the evaluator should reduce allocated objects by up to 16%, reducing GC overhead and memory usage.

To ease the transition into the new formatter we plan to release with v0.18, CUE_EXPERIMENT=formatv2=0 is now allowed as a no-op.

A number of other bugs, panics, and hangs have been resolved as well.

cmd/cue

Module replaces

CUE now supports substituting a module dependency with a local directory or a different remote module during development - for example while testing a fix to a dependency before it is published, or to replace a dependency with a fork including improvements.

This configuration lives in cue.mod/local-module.cue, which is excluded when publishing to registries. cue mod edit and cue mod tidy gain support for maintaining this file.

We have also published a how-to guide on replacing a dependency with a local module.

Read the full design doc in the proposal, or read the cue.mod/local-module.cue reference docs.

Other changes

The new global -C or --chdir flag runs cue from the given working directory.

Command input parsing is improved so that CUE packages can come after data files, such as cue vet -c data.yaml ./schema.

cue import --with-context now ensures that data represents the original raw input data, and not its interpretation like JSON Schema.
cue import --path now skips over null values in an input stream, such as empty documents in a YAML file.

Fix a bug where the flag cue export --path was ignored when the inputs were pure CUE.

The new cue exp gengotypes --outfile flag controls the output file path when generating a single package.

cue vet -d/--schema now supports hidden fields, and correctly reports an error when the command inputs are CUE only.

cue fix and cue trim no longer change file modification times when no changes are necessary.

A $CUE_CACHE_DIR directory is no longer required when loading CUE without external dependencies.

The "filetypes" lookup tables now use a more compact encoding, saving about 150KiB in binary size for cmd/cue as well as Go API users.

LSP server

Add an initial version of organize-imports, which sorts the existing imports and removes unneeded imports. It is not yet capable of suggesting missing imports.

Wait for a short period of inactivity before sending diagnostics to the editor. This "debounce" means that a user typing incomplete CUE syntax will not be distracted with syntax errors as much.

The aliasv2 experiment is now fully supported.

The rename function is fixed to distinguish between field names and aliases.

Improve field name analysis in general so that fields with multiple aliases (e.g. v=[k=string]: _) are properly supported.

Improve attribute handling for file-level embedded attributes, and to attach attributes within expressions to the correct struct.

Treat conjunctions (&) and disjunctions (|) the same way for goto-definition. With the cursor on a path, it returns all results that the path MAY resolve to. With the cursor on a field declaration name, it returns all results that the path constructed from the field's name, and its field's name (and so on) MAY resolve to.

Special-case close function calls so that paths can resolve through fields within the argument to close.

Encodings

⚠️ The experimental JSON Schema encoder now emits most definitions without the leading # character, shortening names and ensuring compatibility with the wider JSON Schema ecosystem. This required deprecating encoding/jsonschema.GenerateConfig.NameFunc in favor of NamesFunc.

The JSON Schema encoder is improved to support list.UniqueItems and standalone validators, to use maxItems and minItems instead of maxLength and minLength for lists with prefix elements, and to generate description keywords for doc comments.

Several closedness bugs in the JSON Schema encoder have been fixed, ensuring that the generated JSON Schema behaves the same way as the original CUE definition.

The JSON Schema decoder is improved to better handle the prefixItems keyword.

The ProtoBuf decoder now resolves relative references following the usual scoping rules, instead of always resolving them against the top-level scope.

Standard library

Add time.ToUnix and time.ToUnixNano, which convert an RFC3339Nano time value into seconds or nanoseconds since the Unix epoch, complementing the existing Unix builtin.

strconv.FormatFloat now accepts a string format parameter, like FormatFloat(3.14, "e", 4, 64).

list.MatchN now shows what expected value it's matching against when it fails.

The net IP APIs now consistently return an error on invalid input types.

Go API

Using cue.Values concurrently is now fully supported, which required deprecating cue.Value.Context. If you encounter any races or bugs, please report them via the issue tracker.

cue/load now supports loading from an io/fs.FS, as outlined in proposal #4285. Loading file embeds through Config.Overlay and Config.FS is supported now as well.

cue/ast/astutil deprecates Sanitize in favor of the new SanitizeFiles API, given that Sanitize on a single file cannot know if another file in the same package shadows builtin names like self.

Add Path.Compare and Selector.Compare, providing allocation-free total ordering suitable for slices.SortFunc.

Clarify that cue/format indents with a tab width of 4 by default.

A new fuzzer has been introduced in the cue package, checking that the parser doesn't crash and that its results are consistent with the rest of the Go APIs like cue/literal. So far, it has already resulted in seventeen bug fixes.

The cue.Interpreter option API has been deprecated in favor of cue.WithInjection, which is a better name going forward.

⚠️ cue/ast.File.Imports, deprecated in mid 2025 in favor of cue/ast.File.ImportSpecs, is now removed.

⚠️ The long-deprecated and hidden cue.Instance methods Lookup, LookupDef, LookupField, and Fill are now removed.

⚠️ The modconfig.Registry interface is changed to report default major versions, which is required for resolving unversioned imports against each dependency module's own defaults. Clients that implement or wrap the interface will need to update. The new interface is future-proofed for upcoming modules changes.