---
title: Date Macros
description: Date Macros protocol schemas
---

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

Date Macro Tokens — the declarative placeholders the UI substitutes

into filter values before sending a query to the data engine.

# Why this lives in `spec`

Filter values in dashboards, views, reports and pages travel as JSON.

Because JSON cannot evaluate code, callers cannot write `daysAgo(30)`

inline; they use a tiny placeholder grammar instead:

\{ published_at: \{ $gte: '\{last_quarter_start\}' \} \}

\{ signal_at:    \{ $gte: '\{30_days_ago\}' \} \}

The placeholders are expanded **client-side** by

`resolveDateMacros()` in `@object-ui/core` immediately before the

filter is handed to the data source. The data engine itself only

sees ISO date / timestamp strings, never `\{tokens\}`.

AI agents and template authors author these placeholders directly,

so the **set of recognised tokens is part of the platform contract**

and must live here next to the rest of the JSON-DSL schemas, not

inside any single UI implementation.

# Two flavours of token

1. **Fixed tokens** — small, finite list (`\{today\}`,

`\{current_quarter_start\}`, `\{last_year_end\}`, …). Enumerated by

`DATE_MACRO_TOKENS` below.

2. **Parameterised tokens** — `\{N_days_ago\}`, `\{N_weeks_from_now\}`,

etc., where `N` is any non-negative integer. Matched by

`DATE_MACRO_PARAM_RE`. Units: `minute(s)`, `hour(s)`, `day(s)`,

`week(s)`, `month(s)`, `year(s)`. Directions: `ago`, `from_now`.

# Out of scope

- CEL expressions (`cel\`daysAgo(30)\``) run **server-side** in the

formula engine. They are unrelated to these placeholders; see

`@objectstack/formula`.

- Token resolution semantics (week-start day, timezone, fiscal

calendars) are defined by the resolver implementation; spec only

freezes the **vocabulary**.

<Callout type="info">
**Source:** `packages/spec/src/data/date-macros.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { DateMacroPlaceholder, DateMacroToken } from '@objectstack/spec/data';
import type { DateMacroPlaceholder, DateMacroToken } from '@objectstack/spec/data';

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

---


---


---

