Proposal: add a try construct to handle optional fields

[mpvl]

📋 Proposal Details:

• File: designs/language/4019-try.md
• Status: Draft

---

Proposal: add a try construct to handle optional fields

Summary

This proposal introduces a try construct to elegantly handle optional fields in CUE configurations, addressing a long-standing source of verbosity and error-prone patterns in the language. Currently, working with optional fields requires explicit existence checks using verbose if exists() statements, and common workarounds using disjunctions (like *foo[a.b] | "fallback") can silently swallow errors when fields are unexpectedly missing—a major source of bugs in CUE configurations.

The proposal introduces two complementary features: the ? notation for field references (e.g., a?, user?.name?) to mark that a field may not exist, and the try comprehension clause that evaluates expressions containing these optional references without producing errors when they're undefined. Together, these features enable concise expressions like x: try { foo?[a?.b]? } else { "fallback" } to replace complex nested conditionals. The try block will simply be discarded if any ?-marked field is undefined, with an optional else clause providing fallback values.

Beyond reducing verbosity, this design creates a symmetry between optional field declarations (field?: type) and their references (field?), enabling better tooling support for detecting potentially brittle code. The explicit marking of optional references makes configuration intent clearer and helps prevent accidentally suppressing errors. The proposal also ensures CUE queries maintain the same semantics as regular field references, leading to more robust and predictable behavior compared to other query languages.

The design carefully scopes the feature to handle only field existence checks, not general conditional logic based on concrete values. Future extensions could include automated detection of error-prone references and conditional field definitions, further improving CUE's reliability and developer experience.

[Summary generated by Claude AI]

---

Full Proposal

The complete proposal with all technical details, examples, and implementation notes can be found in the proposal document.

How to Comment

Please provide feedback on this proposal:

• For general discussion: Comment in this GitHub discussion
• For detailed code review: Comment on the Gerrit CL (link will be added when available)

Last updated: 2025-08-05 18:48:59 UTC

[myitcv]

Adding notes here from a thought offline, so that I can record the thought... and the answer!

I’m trying to sanity-check how try would (or wouldn’t) cover a common “policy” pattern: “if this condition is met, enforce X.”

In CUE terms this breaks down as:

• “if this condition is met” → “does some value ctx unify with condition?”
• “enforce X” → “ctx must also unify with enforce.”

Taking a GitHub Actions flavoured example:

condition: { type: "default branch", on: != "scheduled" }
enforce:   { path: { to: { secret: "my secret" } } }

What I want is essentially the implication:

(ctx ∧ condition)  ⇒  (ctx ∧ enforce)

i.e. if ctx unifies with condition, we must also apply enforce.

My understanding of the try proposal is that it isn't aimed at solving this: it lets you "drop" a failing block, but it doesn’t give you a way to branch on “unification succeeded” vs “unification failed” and then do something else (apply enforce) if it succeeded.

That leads to two questions:

1. Is my read of try correct? i.e. try affects whether a block participates, but doesn’t surface “unification success” as a boolean/guard I can use to conditionally add constraints.

2. Where should this live if not in try? Does this belong as one of the builtins planned from Proposal: core builtin extensions #943?

For the avoidance of doubt: I’m not arguing try should grow this; I’m using the example to check I haven’t misunderstood try, and to ask where we want this capability to live.

[mpvl]

try a.b?.c.d? is really just syntactic sugar for if exists(b) && exists(d) { a.b.c.d }. That is all. It is a very common case, though, and getting the exists call right is tricky, as, generally, they will have to be done in a particular order for it to work correctly. try handles this transparently.

[mpvl]

What you want is foreseen as a builtin:

ctx: { if isValid(self & condition) { enforce } }

where it will enforce that the condition keeps holding once enforce is unified.

We are also considering a "filter" expression, just as exists in JMESPath and JSON Path. Allowing that on the LHS would allow you to "bulk-apply" such constraint using aspect-oriented injection. Suppose we have a map with many contexts:

contexts: [string]: #Context

You could then inject enforce into any context that matches condition using something like this:

contexts: [string][& condition]: enforce

or if we want to keep the LHS and RHS symmetric, it would look like this:

contexts.*[& condition]: enforce

[myitcv]

Just as a thought - given that try is implemented in terms of exists(), but exists() does not yet, well, exist, is it worth implementing that (and other builtins as part of #943) in order to get some experience first?

[infogulch]

try a.b?.c.d? is really just syntactic sugar for if exists(b) && exists(d) { a.b.c.d }

How would exists(d) know that it was referring to a.b.c.d and not x.y.d? Wouldn't this need to be if exists(a.b) && exists(a.b.c.d) { a.b.c.d } ?

[myitcv]

Per our conversation earlier @mpvl, just dropping in some notes here. No action required, just capturing so that I don't lose them.

Somewhat inspired by this example from the proposal:

a: try { expr }

b: if condition { value }

I wondered out loud whether we even "need" try? i.e. could a majority (citation required) of use cases not be covered by simply "collapsing" a declaration if there is an error that is "allowed" by a ? marker?

a: c.b? + 1

Given the above, it would be a "hard" error in case c ultimately failed to resolve and be value that could be dereferenced, but in case c.b failed to resolve it would be as if the declaration above never existed.

Granted this is all rather hand wavey, but that intuition is all my brain can handle!

You kindly pointed out some problems with this approach, specifically the case that the nested try is designed to support:

try {
  a: b? + 1
  try {
    c: d? + 2
  }
}

We discussed the fact that this could equivalently be rewritten in "my" approach as:

a: b? + 1
if exists(a) {
    c: d? + 2
}

Perhaps lots of my "concern" here is whether try holds its weight, a weight which I mainly see in terms the syntax I would be writing/reading/reviewing.

You also shared some of the challenges in finalising the design of try, and some of the implementation challenges.

And finally as a rather "out there" suggestion, I mentioned the potential overlap with an idea we both separately had regarding #1325. Specifically, that in the case of current cue cmd we could envisage a special $if field which gates if a task is run, only allowing the task to be run if the value is true (i.e. not false, and not any error). That is to say, the task being ready is a function of the special $if field. Squinting really hard, we could see values in the same way:

a: c.b? + 1

That is to say that declarations (by which I mean the entire line above, the path and the value - apologies if this is not the correct term) are not "ready" in the case that c.b does not resolve (something we permit by the ? marker) and hence would not contribute to the evaluation result.

[myitcv]

I thought of a shorter more succinct way to convey what I wrote above.

The ? in:

a: c.b? + 1

already says "try" to me. Hence my brain just sees:

try {
    a: c.b? + 1
}

as superfluous syntax.

[infogulch]

Is exists(X) not just (X != _|_)? https://cuelang.org/play/?id=LqkRoqKO3M2#w=function&i=cue&f=eval&o=cue

[rogpeppe]

No, because by current (arguably dubious) semantics, anything noncrete also equates to _|_. https://cuelang.org/play/?id=0bxiPJDH4Ty#w=function&i=cue&f=eval&o=cue

[infogulch]

Oh, that's surprising.

To fill out the list it might be useful to be able to differentiate between three states:

1. concrete value
2. non-concrete constraint (like int or < 5)
3. bottom

I don't think we have enough tools to do this today. If we drop exists(X) and adjust the semantics of == _|_ to only be true when the compared value is actually bottom, and add concrete(X) which returns true if X is concrete, then I think these three states could be distinguished.

On second thought, having exists(X) true for cases 1 & 2, and X != _|_ true for cases 2 & 3 would also be sufficient to distinguish between the three states. So then the choice devolves to backwards compatibility and taste/preference.