Write rules reference

The write rules language, in full. If you haven't met it yet, start with write rules, and the recipes for the patterns most apps need.

This page is generated from the rules engine itself, so it always describes the version that's running. Language version 1.

Statements

A rule set is a list of statements, each ending in ;. Whitespace doesn't matter, and comments are // … or /* … */.

An allow or require statement names the operations it covers: create, update, delete, or write for all three. A restore is checked as an update, and so are the partial-data endpoints.

The optional string after the operations is a label. It shows up in the trace, in the log of refused writes and in the 400 error, so it's worth writing one.

Helpers

let names a value and function names an expression with parameters. Both are top level, and both must be declared before they're used — which is also why recursion can't be written at all, rather than being caught at runtime.

1let isOwner = identity != null && oldItem.identityId == identity.id;
2 
3function total(items) = sum(map(items, i => i.price * i.quantity));
4 
5require update "total": new.total == total(new.lines)
6  else "total must be the sum of the lines";

A let is evaluated once per write, the first time it's read.

Types

Context

What every rule can read:

Context names can't be shadowed by a let, a function or a lambda parameter; the checker says so if you try.

Operators

Access

a.b and a["b"] read an object member; a[i] reads an array element by integer index (there are no negative indexes — use last()).

Reading a missing member, an index past the end, or any member of null gives null. Navigation is null-safe all the way down, so old.a.b.c is simply null on a create. Reading a member of a number, string, boolean, timestamp or duration is an error, because it's almost always a mistake.

Equality and ordering

== and != are deep and structural, with no type coercion (1 == "1" is false), and they never raise an error. The one exception is a timestamp against a string: the string is read as strict ISO-8601, and a string that doesn't parse is simply not equal. That's what makes new.createdAt == now work on data holding "$jsonpad-var:now".

< <= > >= compare number with number, string with string, timestamp with timestamp or ISO string, and duration with duration. Anything else is an error — including null < 3, so a missing field fails closed rather than quietly passing.

Arithmetic

Membership

x in array is deep-equality membership, key in object asks whether the key exists, and sub in string is a substring test. not in is the negation. Any other right-hand side is an error.

Null coalescing

a ?? b is b when a is null. It binds tighter than the comparisons, unlike JavaScript, so new.count ?? 0 >= 3 means (new.count ?? 0) >= 3 — what people mean when they write it.

Precedence

Highest first:

Comparisons and equality don't chain: a < b < c is a syntax error rather than something surprising.

Functions

There are 44 built-in functions. They're pure: none of them reads anything outside the write being checked.

lookup and exists are reserved for reading other items, which rules can't do yet.

Grammar

ruleset        = [ versionDecl ] { statement } ;
versionDecl    = "version" NUMBER ";" ;

statement      = letDecl | functionDecl | sharedDecl | allowStmt | requireStmt ;
letDecl        = "let" IDENT "=" expr ";" ;
functionDecl   = "function" IDENT "(" [ IDENT { "," IDENT } ] ")" "=" expr ";" ;
sharedDecl     = "shared" operations ";" ;
allowStmt      = "allow"   operations [ STRING ] ":" expr ";" ;
requireStmt    = "require" operations [ STRING ] ":" expr [ "else" STRING ] ";" ;
operations     = operation { "," operation } ;
operation      = "create" | "update" | "delete" | "write" ;

expr           = conditional ;
conditional    = logicalOr [ "?" expr ":" expr ] ;
logicalOr      = logicalAnd { "||" logicalAnd } ;
logicalAnd     = equality { "&&" equality } ;
equality       = relational { ( "==" | "!=" ) relational } ;
relational     = coalesce { ( "<" | "<=" | ">" | ">=" | "in" | "not" "in" ) coalesce } ;
coalesce       = additive { "??" additive } ;
additive       = multiplicative { ( "+" | "-" ) multiplicative } ;
multiplicative = unary { ( "*" | "/" | "%" ) unary } ;
unary          = ( "!" | "-" ) unary | postfix ;
postfix        = primary { "." IDENT | "[" expr "]" } ;
primary        = literal | call | IDENT | "(" expr ")" | arrayLit | objectLit ;
call           = IDENT "(" [ argument { "," argument } ] ")" ;
argument       = lambda | expr ;
lambda         = IDENT "=>" expr | "(" [ IDENT { "," IDENT } ] ")" "=>" expr ;
arrayLit       = "[" [ expr { "," expr } [ "," ] ] "]" ;
objectLit      = "{" [ key ":" expr { "," key ":" expr } [ "," ] ] "}" ;
key            = IDENT | STRING ;
literal        = NUMBER | DURATION | STRING | "true" | "false" | "null" ;

Calls are only allowed on names, so there are no method calls and no first-class functions. Lambdas are only allowed as arguments to the higher-order built-ins.

When a rule can't be evaluated

Comparing a number to a string, reading a member of a number, running out of budget: these are evaluation errors, not false.

An error in an allow statement means that statement didn't pass, and if no other one does, the write is refused with 403. An error in a require statement fails it, with the reason. Rules fail closed: a rule set that can't be understood refuses everything rather than letting it through.

&&, || and ?? short-circuit, so identity != null && identity.id == x is safe.