Predicate DSL

Predicates are boolean expressions that determine whether content should be displayed based on date, time, and day of week. They allow you to express time-based scheduling rules like "show on weekdays between 9 AM and 5 PM" or "display only on specific dates."

Context Variables

Predicates have access to three context variables that are provided at evaluation time:

`$DATE`

The current date as a Unix timestamp in milliseconds.

Input range: Any 64-bit signed integer (supports dates before 1970)
Examples:
- 1624579200000 = June 25, 2021 00:00:00 UTC
- -46051200000 = June 15, 1968 (negative timestamps supported)

`$TIME`

The current time of day in milliseconds since midnight.

Value range: 0 to 86400000 (0 ms to 24 hours)
Examples:
- 0 = 00:00:00.000 (midnight)
- 14400000 = 04:00:00.000 (4 AM)
- 46800000 = 13:00:00.000 (1 PM)
- 50000000 = 13:53:20.000

`$WEEKDAY`

The current day of the week as an integer.

Value range: 0 to 6
Encoding:
- 0 = Sunday
- 1 = Monday
- 2 = Tuesday
- 3 = Wednesday
- 4 = Thursday
- 5 = Friday
- 6 = Saturday

Operators

Boolean Literals

Literal	Description
`TRUE`	Always evaluates to true
`FALSE`	Always evaluates to false

Comparison Operators

Compare a variable against a constant value. All comparisons use signed arithmetic.

Operator	Description	Example
`=`	Equal to	`$DATE = 1624579200000`
`<=`	Less than or equal	`$TIME <= 50000000`
`>=`	Greater than or equal	`$TIME >= 54000000`
`<`	Less than	`$DATE < 1630000000000`
`>`	Greater than	`$TIME > 14400000`

Logical Operators

Combine boolean expressions.

Operator	Description	Example
`AND`	Logical conjunction	`$TIME >= 32400000 AND $TIME <= 61200000`
`OR`	Logical disjunction	`$TIME <= 50000000 OR $TIME >= 54000000`
`NOT`	Logical negation	`NOT $WEEKDAY IN {5, 6}`

Special Operators

`BETWEEN {min, max}`

Tests if a value falls within an inclusive range.

$TIME BETWEEN {21600000, 79200000}

Equivalent to: $TIME >= 21600000 AND $TIME <= 79200000

`IN {value1, value2, ...}`

Tests set membership. Particularly useful for weekday filtering.

$WEEKDAY IN {1, 2, 3, 4, 5}

This tests if the current day is Monday through Friday.

Can be negated:

NOT $WEEKDAY IN {5, 6}

Syntax

Grammar

<predicate>   ::= <expression>

<expression>  ::= <term> (("AND" | "OR") <term>)*

<term>        ::= "NOT" <term>
               | "(" <expression> ")"
               | <comparison>
               | <between>
               | <in>
               | "TRUE"
               | "FALSE"

<comparison>  ::= <variable> <comp_op> <number>

<between>     ::= <variable> "BETWEEN" "{" <number> "," <number> "}"

<in>          ::= <variable> "IN" "{" <number_list> "}"
               | "NOT" <variable> "IN" "{" <number_list> "}"

<variable>    ::= "$DATE" | "$TIME" | "$WEEKDAY"

<comp_op>     ::= "=" | "<=" | ">=" | "<" | ">"

<number>      ::= integer (may be negative)

<number_list> ::= <number> ("," <number>)*

Examples

Always True

TRUE

The simplest predicate—always evaluates to true.

Time Range with OR

$TIME <= 50000000 OR $TIME >= 54000000

True when time is before ~13:53 OR after 15:00. This creates a "blackout window" between those times.

Weekday Business Hours

($TIME BETWEEN {32400000, 61200000}) AND (NOT $WEEKDAY IN {0, 6})

Active during business hours (9 AM to 5 PM), excluding weekends (Sunday and Saturday).

Date Range

$DATE >= 1583798400000 AND $DATE <= 1640995200000

Active only between two specific dates.

Multiple Specific Dates

($DATE = 1624665600000) OR ($DATE = 1627257600000) OR ($DATE = 1629936000000)

Active only on specific dates.

Weekday with Time Restriction

($WEEKDAY IN {1, 2, 3, 4, 5}) AND ($TIME BETWEEN {0, 46800000})

Active on weekdays until 1 PM.

Complex Scheduling

(($TIME BETWEEN {0, 46800000}) AND ($DATE = 1624665600000))
OR (($WEEKDAY IN {5, 6}) AND ($TIME <= 14400000))

A complex rule combining:

A specific date with time restriction (until 1 PM)
Weekend mornings (until 4 AM on Friday and Saturday)

Negative Dates (Pre-1970)

$DATE <= -46051200000

Predicates support negative timestamps for dates before the Unix epoch (January 1, 1970).

API Endpoints

You can validate and evaluate predicates programmatically using the API.

Validate Syntax

POST /api/v3/predicate-validation

Check if a predicate expression is syntactically valid. Accepts application/json.

{
  "predicate": "<predicate>"
}

Evaluate Predicate

POST /api/v3/predicate/evaluate

Evaluate a predicate with given context values. Accepts application/json.

{
  "predicate": "$WEEKDAY IN {1, 2, 3, 4, 5}",
  "timestamp": 17683048620000,
  "timezone": "UTC"
}

Field	Description
`predicate`	The predicate expression to evaluate
`timestamp`	Unix timestamp in milliseconds
`timezone`	Timezone for evaluation (e.g., `"UTC"`)

See the API v3 documentation for full details on authentication and usage.