String Functions

Text manipulation is common in DAQS rules: splitting structured names, extracting prefixes, converting numbers to strings for lookup keys. JSONata provides a small set of string functions that cover all of these.

`$string()` — convert any value to a string

$string(311)        /* "311" */
$string(true)       /* "true" */
$string(null)       /* "" */

This function is used constantly in rules that build lookup keys from numeric IDs:

$levelIndex := $merge(
  $[type = "Level"].{ $string(id): name }
);

Without $string(), numeric keys cannot be used in $merge() or $lookup().

`$split()` — split a string into parts

$split("Beton_Gewapend_Constructief", "_")
/* ["Beton", "Gewapend", "Constructief"] */

Access individual parts by index:

$split("Beton_Gewapend_Constructief", "_")[0]   /* "Beton" */
$split("Beton_Gewapend_Constructief", "_")[1]   /* "Gewapend" */

Use $exists() before accessing optional parts:

$parts := $split(name, "_");
$part2 := $exists($parts[2]) ? $parts[2] : ""

This guards against names with fewer parts than expected — without the check, accessing a missing index returns undefined, which can cause validation noise.

Using `$split()` in a rule

$[type = "Material" and values.usedCount > 0].(
  $parts := $split(name, "_");

  {
    "id": id,
    "name": name,
    "part0": $parts[0],
    "part1": $exists($parts[1]) ? $parts[1] : "",
    "part2": $exists($parts[2]) ? $parts[2] : ""
  }
)

`$substring()` — extract a portion of a string

$substring("1.01", 0, 1)    /* "1" */
$substring("Door-A", 5)     /* "A" */

Parameters: $substring(string, start, length?).

start is zero-based
If length is omitted, the rest of the string is returned
Negative start counts from the end of the string

Common use: extracting a prefix

$[type = "Room"].(
  $roomPrefix := $split(values.number, ".")[0];
  $levelPrefix := $split(values.level, " ")[0];

  {
    "id": id,
    "number": values.number,
    "level": values.level,
    "prefixMatch": $roomPrefix = $levelPrefix
  }
)

$split() is often cleaner than $substring() when the split point is a separator character.

`$trim()` — remove surrounding whitespace

$trim("  Office  ")    /* "Office" */

Useful as a defensive step before comparing strings, because Revit parameter values sometimes carry trailing spaces from user input.

Quick reference

Function	What it does	Example
`$string(v)`	Converts any value to a string	`$string(311)` → `"311"`
`$split(s, sep)`	Splits a string by separator	`$split("a_b", "_")` → `["a","b"]`
`$substring(s, n)`	Returns string from position n	`$substring("abc", 1)` → `"bc"`
`$substring(s, n, len)`	Returns len chars from position n	`$substring("abc", 0, 1)` → `"a"`
`$trim(s)`	Removes leading/trailing whitespace	`$trim(" x ")` → `"x"`

Common mistakes

Using $split(name, "_")[1] without $exists() — returns undefined when the name has only one part
Forgetting $string() on numeric IDs when building $merge() keys — causes lookup to silently fail
Using $substring() with a fixed offset when the separator position can vary — prefer $split() when a character separator exists

String Functions

$string() — convert any value to a string

$split() — split a string into parts

Using $split() in a rule

$substring() — extract a portion of a string