Expression language overview

Moltaro uses one small expression language (the Moltaro DSL) wherever an Entity Definition, Board, or another supported configuration surface needs logic without code. You write one expression per setting; the server parses it, checks it against the surface-owned schema, and reports precise errors before anything is saved.

The language has a shared core — literals, comparisons, boolean logic, null checks — and several surfaces that add what makes sense in their context. An expression that is valid as a statement is not automatically valid as a calculated field, so always check the surface-specific page.

Where expressions are used

Surface	Kind	Typical example
Mutation effects — ApplyWhen	Boolean condition	UsePrimary = TRUE AND Product.Price > 0
Field behavior — VisibleWhen, RequiredWhen, EditableWhen	Boolean condition	Status = 'draft' OR Amount IS NULL
Presentation rules — display name and subtitle	Condition + text template	{upper(Code)} — {coalesce(Nickname, Name)}
Statements — reusable named predicates	Boolean condition	DueDate >= @today+7d AND OwnerUser = @currentUserId
Board Statements — Board-owned process predicates for Constraints	Boolean condition over Board Item, Board Data, and a scoped Target	BoardData.Resolution IS NOT EMPTY
Validation rules — object-level save checks	Boolean condition	MATCHES(Code, '^[A-Z]{3}-[0-9]{3}$')
Reference Eligibility — constrain one Reference candidate	Boolean condition over Current and Candidate	Current.Type = 'Bug' AND Candidate.Type IN ('Feature', 'Task')
Calculated fields — stored computed values	Value expression	ROUND(Total * (1 - Discount / 100), 2)
Security Statements and Workflow permissions	Actor-aware Boolean condition	HAS_ROLE('manager') OR RESPONSIBLE(item, 'owner')
Workflow activation preconditions	Actor-independent Boolean condition	COUNT(item.Assemblies) > 0 AND ALL item.Assemblies WHERE (State = 'built')
Workflow DevLog messages	Text template over scalar Subject context	Subject {item.Id}
Task completion requirements	Outcome-specific Boolean condition	Task.OutcomeComment IS NOT EMPTY AND Evidence.HasAttachment = TRUE

How the surfaces differ

• Mutation effects use ApplyWhen to decide whether an automatic write is a candidate before source resolution and fallback selection. They see primary scalar fields, Operation.Mode, and one actor-safe Reference hop; they do not use VisibleWhen, child tables, aggregates, classifier predicates, or runtime variables.
• Field behavior conditions see the record’s own fields and first-level reference paths. They do not support variables such as @today.
• Presentation rules pair a boolean condition with a text template; the template renders field values and a few text functions.
• Entity Statements add @today/@currentUserId variables and direct child-table checks (EXISTS, ANY, ALL, COUNT). They can compare Classifier fields with typed CATEGORY(...) values. Security Statements and Workflow activation preconditions also check related records and nested collections; see Collections and related records.
• Board Statements are reusable predicates for Board Constraints. They add Board Item, Board Data, and an explicitly scoped Target context. Enabled transition, status-entry, status-exit, and mutation-local status-invariant Constraints enforce them.
• Validation rules must return TRUE for the record to save, support @today/@currentUserId, add the MATCHES regex function, and can compare Classifier fields with typed CATEGORY(...) values.
• Reference Eligibility compares the source Current record with a possible Candidate for one scalar Reference. Compiled dependencies drive Form and Table-filter candidate pre-filtering, and the active rule is authoritative for API writes.
• Calculated fields are value expressions, not conditions: arithmetic, numeric/money functions, and aggregate functions over child records.
• Security and Workflow use their selected resource context. Permission rules can inspect the actor; activation business preconditions cannot. Both admit the shared temporal operations and related collections.
• Task completion reads admitted Working Data and completion evidence, with no actor, ambient clock or collection traversal.

The common compiler checks source against each profile. Persisted business decisions execute in PostgreSQL; unsaved draft previews and text-template rendering have their own roles. A preview cannot replace the save or permission decision.

Fail fast with the validation endpoints

The Configuration API validates expressions without saving anything. Rule and validation-rule diagnostics include the offending token and resolved field path. Calculated-field diagnostics return the request field, localized message, and stable code; a valid result also reports the inferred calculation kind. Mutation effects select ContextType: MutationEffect on the shared rule-expression endpoint. Field behavior, mutation effects, presentation rules, and statements share that endpoint but retain different schemas and capabilities. Use these endpoints to iterate until the expression binds cleanly:

• POST …/rule-expressions/validate for field behavior, mutation-effect, presentation, and statement expressions;
• POST …/validation-rules/validate-expression for validation rule expressions;
• POST …/calculation/validate for calculated field expressions (also reports the inferred local or aggregate kind);
• POST /api/workspace/admin/boards/boards/{boardId}/statements/validate for Board Statements. See the Board Statement Configuration API authoring flow.

The entity-definition endpoints belong to the Configuration API reference. For API-first configuration, request the actual language description, discover its paths and validate the source as described in Discover and validate expressions.

Reading order

1. Syntax and types — literals, operators, field paths, null handling.
2. Function reference — every function, grouped by surface.
3. The surface page for what you are configuring: rule expressions, Board Statements, validation rules, Reference Eligibility, or calculated fields.
4. Security and Workflow conditions or Task completion when working in those modules.
5. Discover and validate expressions for developer and agent automation.