---
title: Expression
description: Expression protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

# Expression Protocol

Canonical wire format for all "expression"-shaped metadata across ObjectStack

(formula fields, predicates, conditions, criteria, visibility rules, seed

dynamic values, …).

The persisted form is `\{ dialect, source \}` (and, after `objectstack

compile` normalization, `\{ dialect, ast \}`). String-only shorthand is

accepted at *input* time for developer ergonomics; build emits the canonical

envelope.

## Dialects

| dialect | engine | use |

|:---|:---|:---|

| `cel`   | `@objectstack/formula` (cel-js + ObjectStack stdlib) | formulas, predicates, seed dynamic values |

| `js`    | sandboxed L2 hook bodies (`isolated-vm` / `quickjs`) | mapping, hook bodies |

| `cron`  | `cron-parser` | job schedules |

SQL fragments (analytics joins, partial indexes) are intentionally **not**

routed through this schema — they stay driver-native because their security

posture and portability story differ.

@see content/docs/concepts/north-star.mdx §8 "No private expression DSL"

<Callout type="info">
**Source:** `packages/spec/src/shared/expression.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { Expression, ExpressionDialect, ExpressionMeta, Predicate } from '@objectstack/spec/shared';
import type { Expression, ExpressionDialect, ExpressionMeta, Predicate } from '@objectstack/spec/shared';

// Validate data
const result = Expression.parse(data);
```

---

## Expression

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ |  |
| **source** | `string` | optional |  |
| **ast** | `any` | optional |  |
| **meta** | `Object` | optional |  |


---

## ExpressionDialect

### Allowed Values

* `cel`
* `js`
* `cron`
* `template`


---

## ExpressionMeta

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **rationale** | `string` | optional |  |
| **generatedBy** | `string` | optional |  |


---

## Predicate

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **dialect** | `Enum<'cel' \| 'js' \| 'cron' \| 'template'>` | ✅ |  |
| **source** | `string` | optional |  |
| **ast** | `any` | optional |  |
| **meta** | `Object` | optional |  |


---

