Expression Syntax

Expressions are the language for transforming data in TinySystems. They allow you to select, modify, and combine data as it flows between nodes.

Basic Syntax

All expressions are wrapped in double curly braces:

{{expression}}

Simple Examples

# Reference a value
name: "{{$.userName}}"

# Math operation
total: {{$.price * $.quantity}}

# String concatenation
greeting: "Hello, {{$.name}}!"

The Root Reference: $

The $ symbol represents the root of the incoming data:

// Incoming data
{
  "user": {
    "name": "Alice",
    "email": "alice@example.com"
  },
  "items": [1, 2, 3]
}

# Expression examples
userName: "{{$.user.name}}"     # "Alice"
email: "{{$.user.email}}"       # "alice@example.com"
allData: {{$}}                  # The entire object

Property Access

Dot Notation

Access nested properties with dots:

# $.property.nested.deep
city: "{{$.address.city}}"
zip: "{{$.address.postalCode}}"

Bracket Notation

Use brackets for special characters or dynamic keys:

# $.property["key with spaces"]
value: "{{$.data['my field']}}"

# Dynamic key access
fieldValue: "{{$.data[$.fieldName]}}"

Array Access

By Index

Access array elements by position:

# First element (0-indexed)
first: "{{$.items[0]}}"

# Third element
third: "{{$.items[2]}}"

# Last element
last: "{{$.items[-1]}}"

# Second to last
secondLast: "{{$.items[-2]}}"

Array Length

Get the number of elements:

count: {{$.items.length}}
hasItems: {{$.items.length > 0}}

Expression Types

Pure Expressions

Without quotes, expressions preserve their type:

# Returns number
count: {{$.count}}

# Returns boolean
active: {{$.isActive}}

# Returns object
user: {{$.userData}}

# Returns array
items: {{$.list}}

String Interpolation

With quotes, the result is always a string:

# Returns string "42"
countStr: "{{$.count}}"

# Returns string "true"
activeStr: "{{$.isActive}}"

# Interpolated string
message: "You have {{$.count}} items"

Mixed Content

Combine static text with expressions:

# Multiple expressions in one string
summary: "{{$.firstName}} {{$.lastName}} ({{$.age}} years old)"

# Expressions with formatting
email: "{{$.name}}@{{$.domain}}"
url: "https://api.example.com/users/{{$.userId}}"

Operators

Arithmetic

sum: {{$.a + $.b}}
difference: {{$.a - $.b}}
product: {{$.a * $.b}}
quotient: {{$.a / $.b}}
remainder: {{$.a % $.b}}

Comparison

equal: {{$.a == $.b}}
notEqual: {{$.a != $.b}}
greater: {{$.a > $.b}}
less: {{$.a < $.b}}
greaterOrEqual: {{$.a >= $.b}}
lessOrEqual: {{$.a <= $.b}}

Logical

and: {{$.a && $.b}}
or: {{$.a || $.b}}
not: {{!$.a}}

Ternary (Conditional)

result: "{{$.active ? 'enabled' : 'disabled'}}"
status: {{$.count > 0 ? $.items : []}}

Special Expressions

Default Values

Use || to provide fallbacks:

# Use "Unknown" if name is null/empty
name: "{{$.name || 'Unknown'}}"

# Use 0 if count is undefined
count: {{$.count || 0}}

# Chain defaults
value: "{{$.primary || $.secondary || $.fallback}}"

Null Checks

Check for existence:

hasUser: {{$.user != null}}
isEmpty: {{$.items.length == 0}}

String in Expressions

Strings within expressions use single quotes:

# Compare with string
isAdmin: {{$.role == 'admin'}}

# String literal
default: "{{$.name || 'Anonymous'}}"

Object Construction

Build new objects:

# Simple object
user:
  id: "{{$.userId}}"
  name: "{{$.userName}}"

# Nested structure
response:
  success: true
  data:
    user: {{$.user}}
    timestamp: "{{now()}}"

Array Expressions

Access Elements

# Specific elements
first: {{$.items[0]}}
second: {{$.items[1]}}

# From end
last: {{$.items[-1]}}

Array Properties

length: {{$.items.length}}
isEmpty: {{$.items.length == 0}}

Function Calls

Call built-in functions:

# Current timestamp
timestamp: "{{now()}}"

# Format date
formatted: "{{RFC3339($.date)}}"

# Type conversion
numericString: "{{string($.count)}}"

See Operators and Functions for the complete list.

Escaping

Literal Curly Braces

To output literal {{:

# Use escaped notation
template: "\\{\\{not an expression\\}\\}"

Quotes in Strings

# Single quotes inside double quotes
message: "He said 'hello'"

# Escaped quotes
quote: "She said \"hi\""

Common Patterns

Conditional Mapping

# Map based on condition
status: "{{$.value > 100 ? 'high' : 'normal'}}"

# Complex condition
category: "{{$.age < 18 ? 'minor' : ($.age < 65 ? 'adult' : 'senior')}}"

Safe Navigation

# Use default for potentially missing fields
email: "{{$.user.email || 'not provided'}}"

# Check before access
userName: "{{$.user != null ? $.user.name : 'Guest'}}"

String Formatting

# Build URL
url: "https://api.example.com/{{$.version}}/users/{{$.userId}}"

# Format message
notification: "User {{$.userName}} ({{$.userId}}) logged in at {{now()}}"

Debugging Expressions

Common Errors

Testing Tips

1. Use Debug node to see actual data
2. Start with simple {{$}} to see all data
3. Build expressions incrementally
4. Check types match expectations

Next Steps

• JSONPath Reference - Path syntax details
• Operators and Functions - Available operations
• Expression Examples - Real-world examples