Objectstack Formula

Expressions (CEL) — ObjectStack Formula Protocol

ObjectStack has one expression language across every domain that needs computation or boolean predicates: CEL (Google Common Expression Language). This skill is the canonical reference for AI authors emitting formula / condition / predicate / dynamic-seed metadata.

Strategic context. The future authors of metadata are AI agents.

CEL was chosen because it has (a) a formal grammar, (b) a public training

corpus, (c) AST-first persistence, and (d) sandboxed bounded execution.

The previous custom Salesforce-flavor engine was deleted in M9.5.

>

**Predicates / formulas are bare CEL — never wrap field references in {…}

braces.** The #1 authoring mistake (root cause of #1491) is a condition like

{record.rating} >= 4: in CEL, {…} is a map literal, so it is a parse

error. Write bare CEL: record.rating >= 4. Braces are only for {{ … }}

text templates (see Template surfaces).

>

As of 7.6 (ADR-0032) a malformed expression no longer fails silently.

It used to evaluate to null/false (a flow "fired" but did nothing). Now

objectstack build fails with a located, corrective, schema-aware message

(unknown record.<field> → did-you-mean), and at runtime the engine throws

(the flow/rule fails loudly). The validate_expression agent tool runs the

same shared validator so you can check an expression before saving.

---

Skill Boundaries

---

Core contract

Every expression in metadata is the same envelope:

type Expression = {
  dialect: 'cel' | 'js' | 'cron' | 'template';
  source?: string;
  ast?: unknown;
  meta?: { rationale?: string; generatedBy?: string };
};

Four registered dialects (M9.9):

Authors emit the right dialect for the surface. Bare strings on cron and template fields are auto-wrapped at validate time, but emitting the full envelope is preferred for clarity. cron and template use the same variable scope as CEL — you do not learn three languages.

AI authors: when emitting structured-output JSON for metadata, always

emit the full envelope { dialect, source } — do not emit bare strings.

After M9.7 lands, you will emit ast directly. Until then, emit source

and let objectstack compile parse it.

---

CEL syntax cheat-sheet

has() is NOT a null check

has(record.x) is true whenever the key exists, even when its value is null. To check for "value present and non-blank" use the stdlib helper isBlank() or compare to null explicitly.

Null + string throws

CEL has no implicit null coercion. null + 'foo' throws no such overload: dyn<null> + string. Wrap every nullable string operand in coalesce(..., '').

---

ObjectStack CEL standard library

Registered automatically. Source: `packages/formula/src/stdlib.ts`.

The canonical list is CEL_STDLIB_FUNCTIONS in `packages/formula/src/validate.ts` — a test asserts every entry resolves at runtime, so this table stays in sync with it.

Dates

Numbers

Strings

Collections / null-ish

Plus CEL built-ins: has(x), size(x), int(x), string(x), bool(x), double(x), timestamp(s), duration(s).

If you need a helper that doesn't exist, prefer adding it to the stdlib (small, pure, dependency-free) over inlining a complex CEL expression.

Only the functions above are callable. An UNKNOWN function — PRIOR(), a

legacy ISBLANK(), a typo'd isBlnk() — fails `objectstack build` with a

"no matching overload" type error (#1877), rather than silently no-op'ing the

predicate at run time. Use previous.x (not PRIOR()), isBlank() (not ISBLANK()).

---

Mandatory patterns for AI emission

1. Computed text formula — always coalesce nullable operands

✅ Correct

F`coalesce(record.salutation, '') + ' '
  + coalesce(record.first_name, '') + ' '
  + coalesce(record.last_name, '')`

❌ Wrong (CEL throws on null + string)

F`record.salutation + ' ' + record.first_name + ' ' + record.last_name`

2. Conditional numeric formula — guard divisor

✅

F`coalesce(record.cost, 0) > 0
  ? ((coalesce(record.revenue, 0) - record.cost) * 100.0) / record.cost
  : 0.0`

3. Predicate (field rules / visibility / validation)

✅

P`record.status == 'qualified'`
P`record.amount > 10000 && record.region in ['us', 'eu']`
P`!isBlank(record.po_number)`

For field-level conditional rules, emit the canonical field properties: visibleWhen, readonlyWhen, and requiredWhen. Treat conditionalRequired as a read/compatibility alias only.

❌ Salesforce-flavor — will compile but evaluate to null:

"status = 'qualified'"
"amount > 10000 AND region IN ('us', 'eu')"
"NOT(ISBLANK(po_number))"

4. Dynamic seed value — use cel\\` not new Date()`

✅

{ close_date: cel`daysFromNow(45)`, created_at: cel`now()` }

❌ Compile-time evaluation — every customer gets the package author's clock:

{ close_date: new Date(Date.now() + 45 * 86400000), created_at: new Date() }

This is the determinism gate: objectstack build runs twice produce byte-identical dist/objectstack.json only when seed dates use CEL.

5. Update hook condition — previous vs record

✅

P`previous.status != 'escalated' && record.status == 'escalated'`

ISCHANGED-style logic does not exist as a function; use explicit previous comparison.

---

Mechanical translation table (legacy → CEL)

When migrating Salesforce-flavor metadata, apply these rules in order:

---

Surfaces that take an Expression

All of these spec fields accept string | Expression. The build normalizes to the envelope.

CEL surfaces (predicates + computed values)

Cron surfaces (recurring schedules)

All accept bare strings (auto-wrapped to {dialect:'cron', source}) or the ` cron... helper. 5- or 6-field cron + aliases (@daily, @hourly`, …).

Template surfaces ({{ path }} interpolation)

Mustache subset — a field/variable path plus an optional whitelisted formatter: {{ path }} or {{ path | formatter[:arg] }}. No conditionals, no arbitrary logic (move logic into a CEL field). Same variable scope as CEL. Double braces only — single {x} is not a valid hole.

Formatters (7.6) — value→string is defined per formatter (not implicit):

tmpl`Deal {{ record.name }} — {{ record.amount | currency }} closes {{ record.close_date | date:long }}`

JS surface (sandboxed body)

Reserved for L2 hook bodies / mapping transforms. Use TypeScript source.

---

Cron quick reference

import { cron } from '@objectstack/spec';

schedule: cron`0 6 * * MON`        // every Monday at 06:00
schedule: cron`@daily`             // alias — every midnight
schedule: cron`*/15 * * * *`       // every 15 minutes

Bare strings work too on cron-typed fields, but the cron helper makes intent explicit.

---

Template quick reference

import { tmpl } from '@objectstack/spec';

titleFormat: tmpl`{{record.first_name}} {{record.last_name}}`
subject:     tmpl`Welcome to {{os.org.name}}, {{os.user.name}}!`

Missing paths render as empty string. Date instances are ISO-formatted.

---

Determinism contract

Builds are deterministic only if:

1. All seed dynamic values use cel\...\` (no new Date(), no Date.now()). 2. CEL stdlib helpers honor the pinned now from EvalContext`. 3. No expression source contains random / non-pure data.

CI runs objectstack build twice and asserts SHA-1 match.

---

Open questions (track in ROADMAP M9.7+)

• Authors will emit ast directly once CelExprSchema is published as JSON

Schema for AI constrained decoding (M9.7).

• A visual node-graph editor backed by CelExprSchema is M9.8 (Studio).

---

Verify your work

A malformed expression no longer fails silently (ADR-0032, see the note near the top of this skill): both os validate and os build run the shared validator over every formula and predicate in the stack — CEL syntax plus record.<field> existence on the target object — and fail non-zero with a did-you-mean. Use os validate as the fast post-edit check (no artifact emitted; npm run validate in a scaffolded project). To check a single expression before saving it, call the validate_expression agent tool, which runs the same validator inline.

---

See also

• `content/docs/guides/formula.mdx` — human-facing guide
• `packages/formula/` — engine + stdlib
• `packages/spec/src/shared/expression.zod.ts` — Expression, ExpressionInput, cel / F / P
• ROADMAP M9 — Expression Unification milestone
• north-star §8 — "No private expression DSL"