Rules and formulas
A rule makes a form respond to its own answers: a field appears when another is ticked, a total works itself out, a date must fall after another. Each rule is a formula, a line of text in a small subset of FEEL, the expression language of DMN decision tables. age(date is a formula. The browser, the server's sandbox and the PDF program all read the same text, so they reach the same verdict.
What a rule can do
A rule is stored on a component under rules.
| Key | Effect |
|---|---|
visible | Hidden unless the formula is true. A hidden field's answer is not sent unless the field says otherwise (see Answers of hidden fields). |
enabled | Disabled unless the formula is true. |
readonly | Read-only while the formula is true. |
required | Required while the formula is true, on top of the field's own Required. |
valid | A check on the answer: a non-empty answer is refused with the code rule unless the formula is true. The message is the field's messages.. |
value | A calculation: the field holds the result. No result means no answer. |
default | Used while the field is empty. Browser only. |
filter | Keeps the options of a choice field the formula is true for. Browser only. |
navigation | Blocks moving into or out of a step until the formula holds. Browser only. |
min, max | On a data grid, the fewest and most rows, as a number worked out from other answers. |
Journey pages and routes, and PDF layouts, take formulas too, as a when that chooses the page, route or layout.
{
"id": "end_date",
"type": "date",
"configuration": { "label": "End date", "messages": { "rule": "The end date is on or after the start date." } },
"rules": { "validWhen": "end_date >= start_date" }
}A condition holds only for the yes-or-no true. A number, a text, an empty list or a missing answer does not hold, so compare instead of passing a bare value: email != null, len(items) > 0, status = "paid".
Writing a formula
Numbers are 42 and 3., text is "hello" or 'hello', yes-or-no is true and false, nothing is null, and a calendar day is @"2026-01-31". Keywords are case-sensitive.
Operators, loosest binding first:
| Level | Operators |
|---|---|
| 1 | if ... then ... else ... (else optional; else if chains) |
| 2 | or |
| 3 | and |
| 4 | = (also ==), !=, <, <=, >, >=, between a and b, in (a, b), and the intervals [a..b], (a..b], [a..b), ]a..b[ |
| 5 | + - |
| 6 | * / |
| 7 | unary minus |
not(x) is the way to write not. Comparisons do not chain: a < b < c is an error, write a < b and b < c. Formulas nest at most 100 levels deep.
if age < 18 then "minor" else if age < 65 then "adult" else "senior"
age between 18 and 65
province in ("ON", "QC", "BC")
startDate in [@"2026-01-01"..@"2026-12-31"]else is optional. With no case holding and no else, the result is no answer: a hidden field, an unrequired one, an unset calculation. Write an else when you want a definite value.
Types and empty answers
- Arithmetic (
+ - * /) works on numbers, and on text that is a plain decimal numeral ("3.reads as 3.5;5" "0x10"does not). Anything else, an empty answer,null, a blank or non-numeric text, a yes-or-no, a list, gives no answer, and so does dividing by zero. An empty answer plus 1 is no answer, not 1.+does not join text; useconcat. - Equality is strict:
"1" = 1is false. A missing answer andnullare the same nothing, soratio = nullholds for an unfilled field and for a calculation with no answer, andratio != nullmeans it is known. - Ordering compares two texts by code unit, which orders
YYYY-MM-DDdays as days. Two texts that are both plain numerals compare as numbers ("10" > "9"). Otherwise both sides are read as numbers, and a non-numeric text, a missing answer or a yes-or-no never orders: the comparison is false. and,or,ifhold only fortrue. Anything else, including a missing answer, counts as not holding, andnot(x)holds for anyxthat is nottrue.coalesce(a, b)takes the first value that is notnullor missing. A blank text is a value; wrap it inempty()to test for blank.
Naming fields, rows and variables
A bare name reads a field by its id or data key: quantity, applicant.. A name that is not a plain identifier goes in backticks: `first name`. A hyphen inside a name belongs to it, so write price - discount with spaces to subtract.
Inside a data grid row, three prefixes reach beyond the field itself:
| Prefix | Reads |
|---|---|
row. | A sibling in the same row. |
ancestor. | A field outside the grid, from inside it. |
host. | A value the host supplies, not an answer (see Values from the host). |
component is the field the rule is on, so len(component) >= 3 needs no name. row and row give the row's position and the number of rows. A whole column is read with pluck(items, "amount"), so sum(pluck(items, "amount")) totals a grid. A calculation inside a row runs for each row, so row. gives each line total.
Functions
A function given a value it cannot work with has no result and never throws. Names are camelCase. A parameter ending in ? is optional; ... repeats the last parameter. Each result below is one value; "text" is a string, and a date is a YYYY-MM-DD string.
Logic
| Call | Gives | What it does | Example |
|---|---|---|---|
coalesce(value, ...) | any | The first argument that is not null or missing. | coalesce(nickname, first |
empty(value) | boolean | True when the value is missing, blank, an empty list or a group with nothing ticked. | empty(email) |
is | boolean | True when the value is a number or a text that reads as one. | is |
is | boolean | True when the value is a calendar day written YYYY-MM-DD. | is |
Text
| Call | Gives | What it does | Example |
|---|---|---|---|
concat(value, ...) | text | Joins the arguments into one text; missing values add nothing. | concat(first |
len(value) | number | The number of characters in a text or items in a list. | len(postcode) |
upper(text) | text | The text in upper case. | upper(postcode) |
lower(text) | text | The text in lower case. | lower(email) |
title | text | The text with the first letter of each word in upper case. | title |
trim(text) | text | The text without spaces at either end. | trim(reference) |
starts | boolean | True when the text begins with the prefix. | starts |
ends | boolean | True when the text ends with the suffix. | ends |
contains(haystack, needle) | boolean | True when the text contains the needle, or the list holds it as an item. | contains(languages, "fr") |
substring(text, start, length?) | text | The part of the text from a 1-based position, optionally limited to a length. | substring(sin, 1, 3) |
index | number | The 1-based position of the needle in the text or list, or 0 when absent. | index |
replace(text, find, with) | text | The text with every occurrence of one piece replaced by another. | replace(phone, "-", "") |
split(text, separator) | list | The text cut at each separator, as a list. | split(tags, ",") |
join(list, separator) | text | The list's items as one text with the separator between them. | join(selected(languages), ", ") |
matches(text, pattern) | boolean | True when the whole text matches the regular expression. | matches(postcode, "[A-Z]\d[A-Z] ?\d[A-Z]\d") |
text(value) | text | The value written as text. | text(total) |
pad | text | The text padded at the start with the fill up to the length. | pad |
Numbers
| Call | Gives | What it does | Example |
|---|---|---|---|
sum(value, ...) | number | Adds the arguments; a list argument adds its items. | sum(price, tax) |
min(value, ...) | number | The smallest of the arguments; a list argument contributes its items. | min(quote1, quote2) |
max(value, ...) | number | The largest of the arguments; a list argument contributes its items. | max(quote1, quote2) |
avg(value, ...) | number | The mean of the arguments; a list argument contributes its items. | avg(pluck(scores, "mark")) |
count(value) | number | How many items are selected: a list's length or the ticked boxes of a group. | count(interests) |
abs(number) | number | The number without its sign. | abs(balance) |
round(number) | number | The number rounded to the nearest whole number. | round(total) |
round | number | The number rounded to a count of decimal places. | round |
round | number | The number rounded away from zero, optionally at a count of decimal places. | round |
round | number | The number rounded towards zero, optionally at a count of decimal places. | round |
floor(number) | number | The largest whole number not above the number. | floor(ratio) |
ceil(number) | number | The smallest whole number not below the number. | ceil(ratio) |
modulo(number, divisor) | number | The remainder after dividing by the divisor. | modulo(seats, 4) |
power(base, exponent) | number | The base raised to the exponent. | power(1 + rate, years) |
sqrt(number) | number | The square root of the number. | sqrt(area) |
clamp(number, low, high) | number | The number held between a low and a high bound. | clamp(discount, 0, 100) |
number(text) | number | The text read as a number, or nothing when it does not read as one. | number(amount |
Lists
| Call | Gives | What it does | Example |
|---|---|---|---|
selected(value) | list | The chosen options as a list: a group's ticked boxes, a list as is, one answer alone. | selected(interests) |
first(list) | any | The first item of the list. | first(selected(languages)) |
last(list) | any | The last item of the list. | last(items) |
distinct(list) | list | The list without repeated items, first occurrences kept in order. | distinct(pluck(items, "category")) |
sort(list) | list | The list in ascending order, numbers by value and texts by code unit. | sort(scores) |
reverse(list) | list | The list in the opposite order. | reverse(sort(scores)) |
append(list, item) | list | The list with the item added at the end. | append(selected(languages), "en") |
pluck(rows, key) | list | One column of a repeating section's rows, as a list. | sum(pluck(items, "amount")) |
any(list) | boolean | True when at least one item of the list is true. | any(pluck(items, "taxable")) |
all(list) | boolean | True when every item of the list is true. | all(pluck(items, "confirmed")) |
Dates
| Call | Gives | What it does | Example |
|---|---|---|---|
today() | date | The host's calendar day, YYYY-MM-DD; nothing when the host supplies none. | date |
date(text) | date | The text as a calendar day when it is one written YYYY-MM-DD. | date("2026-01-31") |
date | date | The day moved by an amount of days, weeks, months or years; month ends clamp. | date |
date | number | The signed whole count of days, weeks, months or years from one day to another. | date |
year(date) | number | The year of the day. | year(start |
month(date) | number | The month of the day, 1 to 12. | month(start |
day(date) | number | The day of the month, 1 to 31. | day(start |
day | number | The weekday as a number, 1 for Monday to 7 for Sunday. | day |
start | date | The first day of the day's month. | start |
end | date | The last day of the day's month. | end |
is | boolean | True when the day is a Saturday or a Sunday. | is |
age(date | number | Whole years from the date of birth to the host's day; nothing without a day. | age(date |
Repeating rows
| Call | Gives | What it does | Example |
|---|---|---|---|
row | number | The 1-based position of the current entry in its repeating section. | row |
row | number | How many entries the current repeating section holds. | row |
Details a table row cannot hold:
- A text function reads at most the first 10,000 characters of a text, and a result over 10,000 characters is cut. A list function handed more than 10,000 items gives no result. Either case is reported with a warning that names the function.
lencounts the whole text. - Positions and lengths count code points, so an emoji is one character.
substringandindexcount from 1; a start below 1 starts at the beginning.Of substringwith a length of 0 or less gives an empty text. replaceandsplituse the text as it is, never as a regular expression.matchestakes a regular expression, anchored to the whole text, at most 256 characters. A pattern that does not compile has no result. See Risky patterns.padpads up toStart length;filldefaults to a space; a text already as long is left alone.containsandindexalso work on lists.Of containsgives no answer for a needle that is not text, number or yes-or-no.sumignores empty items and adds the rest; a present item that is not a number makes the sum no answer.sumof nothing is 0.min,maxandavgskip empty items the same way and have no answer when nothing is left.roundrounds halves up (round(2.is 3,5) round(-2.is -2).5) roundrounds halves away from zero atTo scaledecimal places;roundrounds away from zero andUp roundtowards zero, atDown scaleplaces (default 0).modulokeeps the dividend's sign (modulo(-7, 3)is -1) and has no answer for a zero divisor.sqrtof a negative number, andclampwithlowabovehigh, have no answer.numberreads text only.sortorders a list of all numbers or all texts, and has no answer for a mixed list.pluck(rows, key)skips rows that lack the key.anyandallcount only the yes-or-notrueas true.distinctkeeps first occurrences.count(x)andselected(x)read a checkbox group as its ticked options.dateunits areAdd "days","weeks","months"and"years"; a month end clamps (31 January plus one month is the last day of February).dategives a whole signed count, truncated towards zero for weeks, and complete months or years for those units.Diff dayis 1 for Monday to 7 for Sunday.Of Week date(text)reads the first ten characters. A date outside years 1 to 9999 has no result.
The clock
today() is the one call that reads the clock. It gives the host's calendar day as YYYY-MM-DD, with no time of day and no time zone, and age(date is whole years from that day. The browser reads the local date once per recalculation, so every rule in one pass sees the same day. The server uses the day its host supplies as today in the run, so a host that checks a form with today() or age() in it sends its own day. A rule that reads the clock on a server given no day is not replayed there.
Values from the host
A host. name reads a fact about the visit, not an answer: the person's role, the site's region. Any rule can read one, in a grid row or anywhere else. The page supplies the values as the form's host, a plain object. Nested objects are read by dotted name, so host. reads { user: { role: "admin" } }.
form.hostContext = { role: "admin", region: "QC" };
// visibleWhen: host.role = "admin"In the builder, preview these values in Try it's Settings under Host values. Changing host updates the form at once and keeps what was typed. A name the object does not hold has no value, as a missing answer has none. The values are for display. They are not sent with a submission, and a server must never trust the page's. A server judges these rules with values it works out itself, passed as host in the run (see Validation). A server that passes none leaves every rule that reads host. unjudged: the field keeps its own settings, and a calculation keeps the value sent.
On Spring Boot, a Host bean supplies these values (see the host context).
On FastAPI, the host_ keyword of Datum supplies them (see the host context).
Where a rule runs
A rule can be written as { "formula": "...", "run": "..." }. both is the default. browser is applied in the page only, server on the server only, and server-secret on the server only and left out of the definition served to a browser, so a threshold stays private. A host that serves definitions to browsers removes those rules with public.
A formula that cannot be read
A formula with a misspelt function, a missing bracket or a call to a function the running side lacks is a mistake in the formula. The formula-errors attribute on <datum-form> sets what happens:
| Value | Effect |
|---|---|
fail (default) | The form does not open, a submission is refused and the problem is named. |
warn | The rule is dropped and a warning is logged. A valid that cannot be read refuses every non-empty answer instead of being dropped. |
The form's own Form settings panel carries the same choice, stored as formula on the root's configuration, and the host's attribute wins over it. A server run takes it from the run's formula key, else the form's. A problem that stops a server run is reported as formula.. The builder's previews run under warn, so a formula in the middle of typing never closes the builder.
Risky patterns
A regular expression can take exponential time on some text, as (a+)+$ does. A literal pattern in matches(text, "..."), and a field's pattern, are checked when they are written, and one with that shape is refused, with the formula judged by formula-errors. risky-patterns="allow" on <datum-form> lets them through (refuse is the default); a server run takes the same two values as its risky key. The code is pattern.. The default should stay refuse on a server.
In the builder
The Logic workspace lists every rule in the form. New rule offers show, hide, require, validate, enable, read-only, calculate, start at a value, a data grid's minimum and maximum rows, filter a field's options and hold a step. Each rule is a formula with autocomplete and snippets, shows the fields it reads, and warns about problems without blocking Save. The Variables panel on the strip lists the field paths and functions a formula may use, and a click copies one. A "Formula reference" link beside them appears only when the host sets formula on the builder to a page of its own; with none set, no link is drawn. A rule can be tried against sample answers before it is saved, and a test can pin its behaviour (see Testing a form).
Calculations
A value rule gives the field a result the person does not type. The server's sandbox works the result out itself. Calculations that read each other in a loop (a reads b reads a) cannot settle: the browser refuses to open such a form, and a server run refuses the submission with formula..
Your own functions
A plugin adds a function with formula. See Plugins for the registration.
formulaFunctions: [{
name: "taxFor",
params: ["amount", "province"],
returns: "number",
summary: "The sales tax on an amount in a province.",
example: "taxFor(subtotal, province)",
evaluate: ([amount, province]) => (typeof amount === "number" ? amount * (province === "ON" ? 0.13 : 0.05) : undefined)
}]| Member | Meaning |
|---|---|
name | Letters, digits and underscores. A built-in's name, another plugin's, __proto__, constructor and prototype are refused. |
params | Parameter names; one ending in ? is optional. variadic: true repeats the last. min sets the fewest arguments. A call with the wrong number of arguments is a formula problem. |
returns | number, text, boolean, list or date; for the builder's hints. |
summary, example, snippets | What the builder's autocomplete and Variables panel show. |
evaluate | Receives the evaluated arguments as a list and returns a plain value. |
A function is pure and takes its arguments only: no closure over host state, no I/O, no clock, no randomness. If it needs host data, take it as an argument (tax). undefined means no result. A function that throws, or returns something that is not plain data (a number that is not finite, a promise, a function, a Date), gives no result with a warning that names it.
For the server and the PDF program the function must also exist in the sandbox. The plugin's wasm module has a reserved key functions, beside validators:
export default {
functions: {
taxFor: ([amount, province]) => (typeof amount === "number" ? amount * (province === "ON" ? 0.13 : 0.05) : undefined)
}
};A side that lacks the function reads a call to it as no result, so a valid using it fails and a when using it never holds. Test that the two copies agree.