Core Operators

Core operators for accessing data and defining literal values.

var - Variable Access

Access data from the input context.

Syntax

{"var": "path"}
{"var": ["path", default_value]}

Parameters

• path (string): Path to the variable (dot notation, JSON pointer, or array indices)
• default_value (optional, any): Value to return if variable is missing or null

Return Type

Any - Returns the value at the specified path, or the default value if not found

Examples

Basic access:

// Data: {"name": "Alice", "age": 30}
{"var": "name"}  // → "Alice"
{"var": "age"}   // → 30

Nested object access:

// Data: {"user": {"profile": {"city": "NYC"}}}
{"var": "user.profile.city"}  // → "NYC"

Array access:

// Data: {"items": [1, 2, 3, 4, 5]}
{"var": "items.0"}  // → 1
{"var": "items.2"}  // → 3

With default value:

// Data: {"name": "Bob"}
{"var": ["age", 25]}        // → 25 (age missing, returns default)
{"var": ["name", "Guest"]}  // → "Bob" (name exists, returns actual value)

Root context reference:

// Data: [1, 2, 3]
{"var": ""}  // → [1, 2, 3] (returns entire data)

Current context in array operations:

// In map/filter, empty string refers to current element
{"map": [[1, 2, 3], {"var": ""}]}  // → [1, 2, 3]

Path Formats

All formats are normalized internally:

Dot notation:

{"var": "user.profile.name"}

JSON Pointer:

{"var": "/user/profile/name"}

Array indices:

{"var": "items.0"}
{"var": "items[0]"}  // Also supported

Edge Cases

Missing variables:

// Data: {"name": "Alice"}
{"var": "missing"}  // → null

Null values:

// Data: {"value": null}
{"var": "value"}           // → null
{"var": ["value", "default"]}  // → "default" (null treated as missing)

Empty path:

{"var": ""}  // Returns root context

---

$ref / ref - Reference Access

Access data using JSON Schema-style references. Behaves identically to var but uses $ref syntax.

Syntax

{"$ref": "path"}
{"ref": "path"}
{"$ref": ["path", default_value]}

Parameters

Same as var

Return Type

Any - Returns the value at the specified path

Examples

Basic reference:

// Data: {"$params": {"rate": 0.05}}
{"$ref": "$params.rate"}  // → 0.05

JSON Schema style:

{"$ref": "#/properties/user/properties/name"}

With default:

{"$ref": ["missing.field", "default"]}  // → "default"

Notes

• Automatically normalizes JSON Schema paths (removes /properties/ segments)
• Both $ref and ref are supported
• Paths are converted to JSON pointer format internally

---

Literal Values

Define constant values directly in logic expressions.

null - Null Value

null  // → null

bool - Boolean Value

true   // → true
false  // → false

number - Numeric Value

42        // → 42
3.14159   // → 3.14159
-17.5     // → -17.5
0         // → 0

Features:

• Arbitrary precision support via serde_json
• Stored as strings internally to preserve exact precision
• Converted to f64 for arithmetic operations

string - String Value

"hello"         // → "hello"
"Hello World"   // → "Hello World"
""              // → "" (empty string)

array - Array Literal

[1, 2, 3]                    // → [1, 2, 3]
["a", "b", "c"]              // → ["a", "b", "c"]
[1, "hello", true, null]     // → [1, "hello", true, null] (mixed types)
[]                           // → [] (empty array)

Nested arrays:

[[1, 2], [3, 4], [5, 6]]     // → [[1, 2], [3, 4], [5, 6]]

With expressions:

[{"var": "x"}, {"var": "y"}, 10]  // Evaluates expressions inside array

---

Examples

Combining Core Operators

Access nested data with fallback:

{
  "if": [
    {"var": "user.profile.displayName"},
    {"var": "user.profile.displayName"},
    {"var": ["user.name", "Guest"]}
  ]
}

Building complex structures:

{
  "cat": [
    "User: ",
    {"var": "name"},
    " (Age: ",
    {"var": ["age", "Unknown"]},
    ")"
  ]
}

Array manipulation:

{
  "map": [
    {"var": "users"},
    {"var": "name"}
  ]
}
// Extracts name from each user object

---

Best Practices

1. Use dot notation for clearer, more readable paths

   {"var": "user.profile.name"}  // ✓ Clear
   {"var": "/user/profile/name"} // ✓ Also works
   

2. Provide defaults for optional fields

   {"var": ["settings.theme", "light"]}
   

3. Use empty string for current context in array operations

   {"map": [array, {"*": [{"var": ""}, 2]}]}
   

4. Normalize paths consistently (handled automatically)
   • "user.profile" and "/user/profile" are equivalent
   • Both are converted to JSON pointer format internally
5. Handle missing data gracefully

   {"ifnull": [{"var": "optional"}, "default"]}
   

---

Related Operators

• if - Conditional logic based on variable values
• missing - Check for missing variables
• ifnull - Provide fallback for null values
• Array Operators - Transform arrays using var with empty string

---

Performance Notes

• Path normalization happens during compilation, not evaluation
• Variable lookups use zero-copy references for maximum performance
• Compiled logic caches path parsing for repeated evaluations