calculationFormula property, and the formula engine re-evaluates them whenever a dependency changes.
Validation rules
Validation rules are attached to individual questions or table columns using thevalidationRules object in the form configuration JSON.
- Required
- String length
- Numeric range
- Email
- Pattern / regex
- Date range
- File upload
Required field
Makes a field mandatory. The form cannot be submitted until the field contains a value.Use
isRequired: true at the question level for standard questions. For table columns, use column.isRequired: true on the column definition instead.Table column validations
Table questions support the same validation rules on a per-column basis. DefinevalidationRules inside each column object in the tableConfig.columns array.
Validation runs on blur — errors appear when the user leaves a field, not while they are typing. This applies to both top-level questions and table cells.
Calculation formulas
Calculated fields derive their value automatically using a formula expression. SetisCalculated: true and provide a calculationFormula string. The engine re-evaluates the formula each time any referenced field changes.
Basic syntax
Use curly braces{} to reference the value of another question by its questionKey:
Arithmetic operations
All standard arithmetic operators are supported, and expressions can be grouped with parentheses:Mathematical functions
SUM — add multiple values
SUM — add multiple values
AVERAGE — arithmetic mean
AVERAGE — arithmetic mean
MAX — highest value
MAX — highest value
MIN — lowest value
MIN — lowest value
ROUND — round to decimal places
ROUND — round to decimal places
CEILING — round up to nearest integer
CEILING — round up to nearest integer
FLOOR — round down to nearest integer
FLOOR — round down to nearest integer
ABS — absolute value
ABS — absolute value
SQRT — square root
SQRT — square root
POWER — raise to a power
POWER — raise to a power
Function names are case-insensitive.
SUM, Sum, and sum all work identically.Conditional logic
IF / THEN / ELSE
Simple IF — quantity discount
Simple IF — quantity discount
Multiple conditions with AND
Multiple conditions with AND
OR condition
OR condition
IF / ELSEIF / ELSE
Chain multiple conditions usingELSEIF:
Grade classification
Grade classification
Tiered pricing
Tiered pricing
CASE / WHEN
UseCASE to match a field against a set of fixed values — cleaner than a long ELSEIF chain when you are mapping specific codes to results:
Fuel-type emission factor lookup
Fuel-type emission factor lookup
Risk category mapping
Risk category mapping
Referencing option labels
When a question uses a predefined option list (dropdown or select), each option has an internal value and a display label. By default{fieldKey} returns the internal value. Append .label to get the human-readable display label instead:
Table calculations
Table questions store multiple rows of structured data. The formula engine provides several ways to reference that data.Syntax reference
Examples
URL query parameters
Theparam() function lets you read values from the URL query string and use them inside formulas. This is useful for pre-filling context information, applying region-specific factors, or integrating with external systems that append reference IDs to form links.
Syntax
- Returns the string value of the named query parameter.
- Returns an empty string
""if the parameter is absent. - Handles both numeric and text values automatically.
Basic parameter usage
Capture a reference ID from the URL
Capture a reference ID from the URL
?certId=CERT-2024-001
Result: "CERT-2024-001"Display context to the user (read-only)
Display context to the user (read-only)
?certId=CERT-2024-001&locationId=LOC-789
Result: "Submitting data for Certificate: CERT-2024-001 at Location: LOC-789"Parameters in calculations
Numeric parameter in a calculation
Numeric parameter in a calculation
?emissionFactor=0.85
Result: User’s energy consumption × 0.85Parameter with a fallback default value
Parameter with a fallback default value
0.85.Parameters in conditional logic
Certification level based on URL scheme and score
Certification level based on URL scheme and score
?scheme=gold
Result: Determines the certification level using both the URL scheme and the user’s entered score.Regional base rate
Regional base rate
?region=EU
Result: 1.2 (20% premium applied for the EU region)Complex parameter examples
Multiple parameters in one formula
Multiple parameters in one formula
?supplierType=direct&discount=0.9
Result: Calculates cost based on the supplier type and discount factor from the URL.Parameter applied to a table column sum
Parameter applied to a table column sum
?adjustmentFactor=1.15
Result: Sum of the CO2 column multiplied by the adjustment factor from the URL.Common use cases for URL parameters
Parameter security
Safe uses ofparam():
- Capturing reference IDs (validated on the backend)
- Displaying context information to the user
- Pre-filling convenience fields
- Non-sensitive calculations
param():
- Bypassing security or access checks
- Determining prices without backend validation
- Transmitting sensitive data
Complex formula examples
These examples demonstrate how the formula syntax elements combine in real-world carbon management scenarios.Carbon footprint — sum of scopes with conversion
Carbon footprint — sum of scopes with conversion
Conditional discount with VAT
Conditional discount with VAT
Tiered emissions cost calculation
Tiered emissions cost calculation
Three-tier pricing: first 1,000 tCO2e at £15, next 4,000 at £12, everything above 5,000 at £10.
Normalised score using nested functions
Normalised score using nested functions
Percentage change from baseline
Percentage change from baseline
Guards against division by zero when the baseline is zero.
Table column sum with zero guard
Table column sum with zero guard
Important notes
Validation behaviour
- Validation errors appear on blur — when the user leaves a field, not while they are typing.
- Use
isRequired: trueat the question level; usecolumn.isRequired: truefor table column definitions. - Remember to double-escape backslashes in JSON regex patterns: write
\\dto represent the regex\d. - File sizes must be specified in bytes: 1 MB =
1048576, 5 MB =5242880.
Formula execution and correctness
- Execution order — the engine re-evaluates a formula each time any of its referenced fields change. Ensure source fields are answered before calculated fields that depend on them.
- Circular dependencies — do not create formulas that reference each other, directly or indirectly. Circular references cause evaluation loops and must be avoided.
- String literals — wrap string constants in double quotes inside the formula string:
"Active","USA". - Case sensitivity — function names are case-insensitive (
SUM,Sum,sumall work). - Division by zero — always guard division operations with an
IFcheck when the denominator could be zero, as shown in the percentage change example above. - Floating-point precision — use
ROUNDon final results to avoid displaying long decimal tails caused by floating-point arithmetic. - Table data access — use the
tableKey[rowIndex].columnKeysyntax for specific cells, orCOLUMN_SUM/ROW_SUMhelper functions for aggregates. - URL parameters —
param("name")returns an empty string when the parameter is absent; always provide a fallback using anIFcheck if the parameter is required for a numeric calculation.
Performance guidance
- Keep individual formulas simple and readable. Break complex calculations into a chain of intermediate calculated fields.
- Prefer
CASEover longELSEIFchains when mapping a fixed set of values. - Apply
ROUNDto final output fields rather than rounding at each intermediate step.