Introduction

datalogic-rs is a JSONLogic rules engine: one Rust core with official bindings for Rust, Node.js, the browser (WASM), Python, Go, Java, .NET, and PHP, plus a React visual debugger. Rules are plain JSON; the same rule evaluates with identical semantics in every runtime, verified by a 2,128-case conformance battery that runs against the same core every binding ships.

This site is the reference documentation. For the project pitch, benchmarks, and package matrix, see the GitHub repository; to try rules in your browser, open the playground.

What is JSONLogic?

JSONLogic is a standard for expressing logic rules as JSON. A rule is:

• Portable: you store it in a database, send it over an API, or embed it in configuration
• Language-agnostic: the same rule runs on any conforming implementation
• Readable: a reviewer reads the rule itself, with no host code around it
• Safe: evaluating a rule runs no code the rule supplies

A JSONLogic rule is a JSON object where the key is the operator name and the value is an array of arguments:

{"operator": [arg1, arg2, ...]}

For example:

{"and": [
  {">": [{"var": "age"}, 18]},
  {"==": [{"var": "country"}, "US"]}
]}

This rule checks that age > 18 and country == "US".

How the engine works

datalogic-rs works in two phases:

1. Compilation: the engine parses the rule and compiles it into a reusable Logic. This phase:

   • assigns each built-in operator an OpCode, and each custom operator a slot on the engine
   • evaluates constant subexpressions once
   • builds output templates in templating mode

2. Evaluation: the engine runs the compiled logic against your data with:

   • OpCode dispatch, with no operator-name lookup at runtime
   • arena-allocated results that can borrow from the input without copying
   • a context stack for iterator bodies (map, filter, reduce)

Every binding exposes this compile-once, evaluate-many pattern; Performance has the numbers.

Before a rule runs, you can validate it statically: Engine::check (check in every binding) reports unknown operators with a “did you mean” suggestion, wrong argument counts, and other mistakes—each with a JSON Pointer into the rule (Rule Analysis). The MissingVar::Error setting turns a read of a misspelled data path into a VariableNotFound error instead of null (Configuration), ops_budget bounds untrusted execution (Operation Budget), and Engine::operators() lists every operator compiled into your build (API Reference).

Find your language

Each language has its own chapter with install steps, a quick start, and the full API surface:

How these docs are organized

• Getting Started: installation, first evaluation, core concepts, and starter service boilerplates
• Operators: reference for all 84 built-in operators, with runnable examples on every page
• Languages: one chapter per binding (see the table above)
• Guides: custom operators, configuration, rule analysis, operation budget, structured objects / templating, thread safety, security & sandboxing, and service integrations (Express, Spring Boot)
• Reference: use-case cookbook, performance, comparisons, migration, FAQ, and troubleshooting

Next steps

• Installation: add datalogic-rs to your project
• Quick Start: run your first evaluation
• Basic Concepts: understand compilation, sessions, and evaluation
• Starter Boilerplates: copy-paste Express, FastAPI, and Axum services
• Use Cases & Examples: feature flags, pricing, validation, and fraud scoring
• Coming from json-logic-js?: run your existing rules unchanged
• Migration Guide: upgrade from v4 or review behavior changes across 5.x releases

Playground (inline)

The Full-Page Visual Editor adds visual editing, engine settings and resizable panels. This page embeds the same editor inline, with a read-only diagram, for quick checks.

Try JSONLogic expressions in your browser. This playground runs the @goplasmatic/datalogic-ui debugger on the datalogic-rs 5.9.0 engine, compiled to WebAssembly.

How to Use

1. Logic: Enter your JSONLogic expression in the Logic panel
2. Data: Enter the JSON data to evaluate against in the Data panel
3. Result: Read the evaluated output, or the engine’s error with its type and failing operator
4. Diagram: View the diagram of your logic expression and step through the evaluation with the debugger controls (Space, arrow keys, Home/End once you click the diagram)
5. Examples: Use the Load Example… dropdown to load pre-built examples
6. Templating: Tick the checkbox to compile multi-key objects as output templates with embedded JSONLogic

Quick Reference

Basic Operators

Array Operations

String Operations

Example: Feature Flag

Determine if a user has access to a premium feature:

{
  "and": [
    {"==": [{"var": "user.plan"}, "premium"]},
    {">=": [{"var": "user.accountAge"}, 30]}
  ]
}

Data:

{
  "user": {
    "plan": "premium",
    "accountAge": 45
  }
}

Example: Dynamic Pricing

Calculate a discounted price based on quantity:

{
  "if": [
    {">=": [{"var": "quantity"}, 100]},
    {"*": [{"var": "price"}, 0.8]},
    {"if": [
      {">=": [{"var": "quantity"}, 50]},
      {"*": [{"var": "price"}, 0.9]},
      {"var": "price"}
    ]}
  ]
}

Data:

{
  "quantity": 75,
  "price": 100
}

Learn More

• Operators Overview: Full operator documentation
• Getting Started: Using the library in your stack
• React Visual Debugger: Embed this visual editor and debugger into your own React app
• Use Cases & Examples: Real-world recipes for feature flags, pricing, and validation

Installation

Adding to Your Project

Pick your language. Each package carries the core crate’s version number (5.9.0 for this release):

// Cargo.toml
[dependencies]
datalogic-rs = "5"

Or run in terminal:
cargo add datalogic-rs

// npm
npm install @goplasmatic/datalogic-node # for Node.js services (native FFI)
# or:
npm install @goplasmatic/datalogic-wasm # for Browsers / Bun / Workers (WASM)

# pip
pip install datalogic-py

// go.mod
go get github.com/GoPlasmatic/datalogic-rs/bindings/go/v5

// Maven: pom.xml
<dependency>
    <groupId>io.github.goplasmatic</groupId>
    <artifactId>datalogic</artifactId>
    <version>5.9.0</version>
</dependency>

// Gradle: build.gradle.kts
implementation("io.github.goplasmatic:datalogic:5.9.0")

// dotnet CLI
dotnet add package Goplasmatic.Datalogic

// Composer
composer require goplasmatic/datalogic

The Rust crate builds without serde_json by default: the main entry points (Engine::eval_str, Engine::compile(&str), datalogic_rs::eval_str) take and return JSON text. Add the serde_json feature if you need serde_json::Value interop or the typed eval_into::<T> paths.

Feature Flags

The crate is a small core plus opt-in features. With default = [] you get the 33 JSONLogic core operators and no optional dependencies:

Example: opt into serde_json::Value interop plus templating:

[dependencies]
datalogic-rs = { version = "5", features = ["serde_json", "templating"] }
serde_json = "1.0"

Example: every operator, plus serde_json interop and templating (the official bindings use this set, plus trace and budget):

[dependencies]
datalogic-rs = { version = "5", features = ["all-operators", "serde_json", "templating"] }

A Cargo feature decides what is compiled in. To give one engine fewer operators than the build has, list the families it keeps with Engine::builder().with_families(..) (families in the bindings); see Configuration.

Version Selection

• v5.x (current, 5.9.0): string-based API, opt-in serde_json, builder-only operator registration. v4 code has no compatibility shim in v5, so plan a single cutover.
• v4.x: DataLogic engine with a serde_json::Value-first API. No longer the active line.
• v3.x: the arena-based engine that v4 replaced.

If you’re upgrading from v4, or from an earlier 5.x release, see the Migration Guide.

Other languages

The Rust crate is the engine; each other language has its own binding over it. The binding’s guide covers install details and the API in that language:

Building the WASM binding from source:

cd bindings/wasm
./build.sh

Minimum Rust Version

datalogic-rs requires Rust 1.98 or later (the rust-version in its Cargo.toml). The floor comes from the datavalue-rs 0.3 dependency, which declares 1.98; the crate’s own code uses edition 2024 and needs less. The crate sets #![forbid(unsafe_code)].

Verifying Installation

Run a one-line evaluation to confirm the package loads:

// main.rs
fn main() {
    let result = datalogic_rs::eval_str(r#"{"+": [1, 2]}"#, r#"{}"#).unwrap();
    println!("1 + 2 = {}", result);
    assert_eq!(result, "3");
}
// Run in terminal: cargo run

// index.js
import { apply } from '@goplasmatic/datalogic-node';

const result = apply({ '+': [1, 2] }, {});
console.log(`1 + 2 = ${result}`); // 1 + 2 = 3
// browser/edge: same API via @goplasmatic/datalogic-wasm, see the WASM chapter

# test.py
from datalogic_py import apply

result = apply({"+": [1, 2]}, {})
print(f"1 + 2 = {result}") # 1 + 2 = 3

// main.go
package main

import (
    "fmt"
    datalogic "github.com/GoPlasmatic/datalogic-rs/bindings/go/v5"
)

func main() {
    result, _ := datalogic.Apply(`{"+": [1, 2]}`, `{}`)
    fmt.Printf("1 + 2 = %s\n", result) // 1 + 2 = 3
}

// Main.java
import com.goplasmatic.datalogic.Engine;

public class Main {
    public static void main(String[] args) {
        try (Engine engine = new Engine()) {
            String result = engine.apply("{\"+\": [1, 2]}", "{}");
            System.out.println("1 + 2 = " + result); // 1 + 2 = 3
        }
    }
}

// Program.cs
using Goplasmatic.Datalogic;

using var engine = new Engine();
var result = engine.Apply("""{"+": [1, 2]}""", "{}");
Console.WriteLine($"1 + 2 = {result}"); // 1 + 2 = 3

<?php // test.php
require 'vendor/autoload.php';

use Goplasmatic\Datalogic\Engine;

$engine = new Engine();
echo "1 + 2 = " . $engine->apply('{"+": [1, 2]}', '{}'); // 1 + 2 = 3

Next Steps

• Quick Start: run your first one-shot and compiled evaluations
• Basic Concepts: learn how rules, compilation, sessions, and the context stack work
• Starter Boilerplates: copy-paste service setups for Express, FastAPI, and Axum
• Operators Overview: browse all 84 built-in operators
• Troubleshooting: fix common build, bundler, and FFI loader issues

Quick Start

This page takes you from a one-shot evaluation to a reusable Engine.

The simplest path: one-shot helpers

For a one-off evaluation with default settings, call the module-level helper; you don’t build an engine first.

let result = datalogic_rs::eval_str(
    r#"{">": [{"var": "score"}, 50]}"#,
    r#"{"score": 75}"#,
).unwrap();
assert_eq!(result, "true");

import { apply } from '@goplasmatic/datalogic-node';

const result = apply(
  { '>': [{ var: 'score' }, 50] },
  { score: 75 }
);
console.log(result); // true
// browser/edge: same API via @goplasmatic/datalogic-wasm, see the WASM chapter

from datalogic_py import apply

result = apply(
    {">": [{"var": "score"}, 50]},
    {"score": 75}
)
print(result) # True

result, _ := datalogic.Apply(
    `{">": [{"var": "score"}, 50]}`,
    `{"score": 75}`,
)
fmt.Println(result) // "true"

import com.goplasmatic.datalogic.Engine;

try (Engine engine = new Engine()) {
    String result = engine.apply(
        "{\">\": [{\"var\": \"score\"}, 50]}",
        "{\"score\": 75}"
    );
    System.out.println(result); // "true"
}

using Goplasmatic.Datalogic;

using var engine = new Engine();
var result = engine.Apply(
    """{">": [{"var": "score"}, 50]}""",
    """{"score": 75}"""
);
Console.WriteLine(result); // "true"

use Goplasmatic\Datalogic\Engine;

$engine = new Engine();
$result = $engine->apply(
    '{">": [{"var": "score"}, 50]}',
    '{"score": 75}'
);
echo $result; // "true"

The module-level helpers (eval_str in Rust, apply in Node.js, Python and Go) run on a default engine. Java, C# and PHP have no module-level function, so a default Engine and its apply method give the same one-shot. Use them for scripts, tutorials and code that needs no custom operators or configuration.

When you need an Engine

Build an Engine when you need custom operators, a non-default configuration, templating mode, or a long-lived Session that reuses memory in a hot loop.

use datalogic_rs::Engine;

// 1. Create an engine
let engine = Engine::new();

// 2. Compile a rule once (returns reusable compiled Logic)
let compiled = engine.compile(r#"{">": [{"var": "score"}, 50]}"#).unwrap();

// 3. Evaluate against data via a Session (reuses memory buffer)
let mut session = engine.session();
let result = session.eval_str(&compiled, r#"{"score": 75}"#).unwrap();
assert_eq!(result, "true");
session.reset(); // Reset between evaluations to keep memory flat

import { Engine } from '@goplasmatic/datalogic-node';

// 1. Create an engine
const engine = new Engine();

// 2. Compile once (returns a reusable Rule)
const rule = engine.compile({ '>': [{ var: 'score' }, 50] });

// 3. Evaluate via a session (reuses the arena across calls)
const sess = engine.session();
const result = sess.evaluate(rule, { score: 75 });
console.log(result); // true
// browser/edge: same API via @goplasmatic/datalogic-wasm, see the WASM chapter

from datalogic_py import Engine

# 1. Create an engine
engine = Engine()

# 2. Compile once
rule = engine.compile({">": [{"var": "score"}, 50]})

# 3. Evaluate
result = rule.evaluate({"score": 75})
print(result) # True

// 1. Create engine (defer close to prevent FFI leak)
engine := datalogic.NewEngine()
defer engine.Close()

// 2. Compile once (defer close to prevent FFI leak)
rule, _ := engine.Compile(`{">": [{"var": "score"}, 50]}`)
defer rule.Close()

// 3. Open session for evaluation (defer close to prevent FFI leak)
session := engine.Session()
defer session.Close()

result, _ := session.Evaluate(rule, `{"score": 75}`)
fmt.Println(result) // "true"

import com.goplasmatic.datalogic.Engine;
import com.goplasmatic.datalogic.Rule;
import com.goplasmatic.datalogic.Session;

// 1. Create an engine, 2. compile once, 3. evaluate via a session;
// try-with-resources frees the native handles
try (Engine engine = new Engine();
     Rule rule = engine.compile("{\">\": [{\"var\": \"score\"}, 50]}");
     Session session = engine.openSession()) {
    String result = session.evaluate(rule, "{\"score\": 75}");
    System.out.println(result); // "true"
}

using Goplasmatic.Datalogic;

// 1. Create an engine
using var engine = new Engine();

// 2. Compile once
using var rule = engine.Compile("""{">": [{"var": "score"}, 50]}""");

// 3. Evaluate via a session (arena reuse across calls)
using var session = engine.OpenSession();
var result = session.Evaluate(rule, """{"score": 75}""");
Console.WriteLine(result); // "true"

use Goplasmatic\Datalogic\Engine;

// 1. Create an engine
$engine = new Engine();

// 2. Compile once
$rule = $engine->compile('{">": [{"var": "score"}, 50]}');

// 3. Evaluate via a session (arena reuse across calls)
$session = $engine->openSession();
$result = $session->evaluate($rule, '{"score": 75}');
echo $result; // "true"

The Rust chapter and each language’s chapter cover engine configuration and sessions in depth.

Working with Variables

Access data using the var operator:

// Simple variable access
{ "var": "name" }
// Data: { "name": "Alice" }
// Result: "Alice"

// Nested access with dot notation
{ "var": "user.address.city" }
// Data: { "user": { "address": { "city": "New York" } } }
// Result: "New York"

// Default value for missing keys
{ "var": ["missing_key", "default_value"] }
// Data: {}
// Result: "default_value"

Try it:

Conditional Logic

Use if for branching:

{ "if": [{ ">=": [{ "var": "age" }, 18] }, "adult", "minor"] }

// Data: { "age": 25 }
// Result: "adult"

// Data: { "age": 15 }
// Result: "minor"

Try it:

Combining Conditions

Use and and or to combine conditions:

// AND: all conditions must be true
{ "and": [
    { ">=": [{ "var": "age" }, 18] },
    { "==": [{ "var": "verified" }, true] }
] }
// Data: { "age": 21, "verified": true }
// Result: true

// OR: at least one condition must be true
{ "or": [
    { "==": [{ "var": "role" }, "admin"] },
    { "==": [{ "var": "role" }, "moderator"] }
] }
// Data: { "role": "admin" }
// Result: true

Try it:

Array Operations

Filter, map, and reduce arrays:

// filter: keep elements matching a condition ("" is the current element)
{ "filter": [{ "var": "numbers" }, { ">": [{ "var": "" }, 5] }] }
// Data: { "numbers": [1, 3, 5, 7, 9] }
// Result: [7, 9]

// map: transform each element
{ "map": [{ "var": "numbers" }, { "*": [{ "var": "" }, 2] }] }
// Data: { "numbers": [1, 2, 3] }
// Result: [2, 4, 6]

Try it:

Error Handling

A failed evaluation is a structured error: a stable type tag, a message, the innermost operator that failed, and a breadcrumb of compiled-node ids leading to it:

{ "+": ["text", 1] }
// Data: {}
// Error: { "type": "Thrown", "message": "Thrown: {\"type\":\"NaN\"}", "thrown": { "type": "NaN" }, "operator": "+", "node_ids": [3] }

The tag here is Thrown; its thrown payload is the JSONLogic-style {"type": "NaN"} value that arithmetic raises on a non-numeric string.

To recover from a runtime error inside the rule, wrap the expression in try (in the Rust crate, enable the error-handling feature; every language binding has it):

{ "try": [{ "/": [10, { "var": "divisor" }] }, 0] }
// Data: { "divisor": 0 }
// Result: 0 (the division throws, so the fallback is returned)

Try it:

Each binding’s chapter covers how an uncaught error reaches your code (Rust Result, JavaScript and Python exceptions, Go error values, Java, C# and PHP exceptions): Node.js, browser WASM, Python, Go, Java, .NET, PHP.

compile accepts an unknown operator and leaves it to fail when evaluation reaches it. To catch such mistakes first, run check on the rule (Engine::check in Rust): it lists unknown operators with a “did you mean” suggestion and wrong argument counts, each located by a JSON Pointer (Rule Analysis). To make a misspelled data path fail instead of reading as null, set MissingVar::Error ("missing_var": "error" in a binding’s config; see Configuration).

Next Steps

• Basic Concepts: how rules, compilation, sessions, and evaluation fit together
• Starter Boilerplates: Express, FastAPI, and Axum service templates
• Operators: every built-in operator with runnable examples
• Use Cases & Examples: complete rule patterns for real workloads
• Language chapters: Rust, Node.js, JavaScript in the browser (WASM), Python (Quick Start), Go (Quick Start), Java / Kotlin, .NET, PHP

Basic Concepts

This page covers the model behind datalogic-rs: rules, compilation, evaluation and the engine.

JSONLogic Format

A JSONLogic rule is a JSON object where:

• The key is the operator name
• The value is an array of arguments (or a single argument)

{ "operator": [arg1, arg2, ...] }

Arguments can be:

• Literal values: 1, "hello", true, null
• Arrays: [1, 2, 3]
• Nested operations: { "var": "x" }

Examples

// Simple comparison
{ ">": [5, 3] }  // true

// Variable access
{ "var": "user.name" }  // Access user.name from data

// Nested operations
{ "+": [{ "var": "a" }, { "var": "b" }] }  // Add two variables

// Multiple arguments
{ "and": [true, true, false] }  // false

Compilation vs Evaluation

datalogic-rs works in two phases: you compile a rule once, then evaluate it against as many data payloads as you need.

Compilation Phase

When you compile a rule, the engine parses the JSON, resolves operator names to OpCodes (and custom operators to their slot on the engine), runs constant folding, strength reduction, dead-branch removal and common-subexpression elimination, and returns an immutable compiled tree you can reuse:

// Compiles to a reusable Logic AST
let compiled = engine.compile(r#"{">": [{"var": "x"}, 10]}"#).unwrap();

// Logic is Send + Sync; wrap in Arc for cross-thread sharing
let shared = std::sync::Arc::new(compiled);

// Compiles to a reusable Rule handle
const rule = engine.compile({ '>': [{ var: 'x' }, 10] });
// browser/edge: same API via @goplasmatic/datalogic-wasm, see the WASM chapter

# Compiles to a reusable Rule object
rule = engine.compile({">": [{"var": "x"}, 10]})

// Compiles to a reusable *Rule
rule, _ := engine.Compile(`{">": [{"var": "x"}, 10]}`)
defer rule.Close()

// Compiles to a reusable Rule (AutoCloseable; thread-safe, share freely)
Rule rule = engine.compile("{\">\": [{\"var\": \"x\"}, 10]}");

// Compiles to a reusable Rule (IDisposable; thread-safe, share freely)
using var rule = engine.Compile("""{">": [{"var": "x"}, 10]}""");

// Compiles to a reusable Rule object
$rule = $engine->compile('{">": [{"var": "x"}, 10]}');

compile accepts a rule with an unknown operator and leaves it to fail when evaluation reaches it. check reports that and other mistakes before anything runs, and compile_checked (compileChecked in the bindings) refuses such a rule; see Rule Analysis.

Evaluation Phase

During evaluation, the engine dispatches each node by its OpCode and reads from the data context. Intermediate values live in a memory arena: a fresh one per one-shot call, or the one a session owns.

To evaluate a compiled rule against data with a reusable session:

let engine = Engine::new();
let compiled = engine.compile(r#"{">": [{"var": "x"}, 10]}"#).unwrap();

// Reusable session: reuses the memory buffer across calls.
let mut session = engine.session();
let result = session.eval_str(&compiled, r#"{"x": 42}"#).unwrap();
assert_eq!(result, "true");
session.reset(); // Reset between batches

import { Engine } from '@goplasmatic/datalogic-node';

const engine = new Engine();
const rule = engine.compile({ '>': [{ var: 'x' }, 10] });

// Session reuses one arena across calls
const sess = engine.session();
const result = sess.evaluate(rule, { x: 42 });
console.log(result); // true
// browser/edge: same API via @goplasmatic/datalogic-wasm, see the WASM chapter

from datalogic_py import Engine

engine = Engine()
rule = engine.compile({">": [{"var": "x"}, 10]})

# Direct evaluation against python dictionaries
result = rule.evaluate({"x": 42})
print(result) # True

engine := datalogic.NewEngine()
defer engine.Close()

rule, _ := engine.Compile(`{">": [{"var": "x"}, 10]}`)
defer rule.Close()

session := engine.Session()
defer session.Close()

result, _ := session.Evaluate(rule, `{"x": 42}`)
fmt.Println(result) // "true"

// try-with-resources frees the native handles
try (Engine engine = new Engine();
     Rule rule = engine.compile("{\">\": [{\"var\": \"x\"}, 10]}");
     Session session = engine.openSession()) {
    String result = session.evaluate(rule, "{\"x\": 42}");
    System.out.println(result); // "true"
}

using var engine = new Engine();
using var rule = engine.Compile("""{">": [{"var": "x"}, 10]}""");

// Session reuses one arena across calls
using var session = engine.OpenSession();
var result = session.Evaluate(rule, """{"x": 42}""");
Console.WriteLine(result); // "true"

$engine = new Engine();
$rule = $engine->compile('{">": [{"var": "x"}, 10]}');

// Session reuses one arena across calls
$session = $engine->openSession();
$result = $session->evaluate($rule, '{"x": 42}');
echo $result; // "true"

The Engine

The Engine holds the evaluation configuration and the registered custom operators.

To build and configure an engine in each runtime:

use datalogic_rs::{Engine, EvaluationConfig};

// 1. Default engine
let engine = Engine::new();

// 2. Engine with custom configurations
let engine = Engine::builder()
    .with_config(EvaluationConfig::strict())
    .build();

// 3. Engine with custom operators
let engine = Engine::builder()
    .add_operator("double", DoubleOperator)
    .build();

import { Engine } from '@goplasmatic/datalogic-node';

// 1. Default engine
const engine = new Engine();

// 2. Engine with custom operators
const engineWithOps = new Engine({}, {
  double: (argsJson) => {
    const args = JSON.parse(argsJson);
    return JSON.stringify(args[0] * 2);
  }
});

import json
from datalogic_py import Engine

# 1. Default engine
engine = Engine()

# 2. Configured engine with custom operators
engine_with_ops = Engine(
    templating=True, # Enable JSON templating mode
    custom_operators={
        "double": lambda args_json: json.dumps(json.loads(args_json)[0] * 2)
    }
)

import datalogic "github.com/GoPlasmatic/datalogic-rs/bindings/go/v5"

// 1. Default engine
engine := datalogic.NewEngine()
defer engine.Close()

// 2. Engine with custom operators via a fluent builder
engineWithOps, err := datalogic.NewEngineBuilder().
    AddOperator("double", func(argsJson string) (string, error) {
        // implementation
        return "result", nil
    }).
    Build()
if err != nil {
    panic(err)
}
defer engineWithOps.Close()

import com.goplasmatic.datalogic.Engine;

// 1. Default engine (AutoCloseable; close it when done)
Engine engine = new Engine();

// 2. Engine with custom operators via the builder
// (argsJson is a JSON array string; parse with your JSON library, Jackson shown)
Engine engineWithOps = Engine.builder()
    .addOperator("double", argsJson -> {
        int n = mapper.readTree(argsJson).get(0).asInt();
        return String.valueOf(n * 2);
    })
    .build();

using Goplasmatic.Datalogic;

// 1. Default engine
using var engine = new Engine();

// 2. Engine with custom operators via the builder
using var engineWithOps = Engine.Builder()
    .AddOperator("double", argsJson =>
    {
        var n = System.Text.Json.Nodes.JsonNode.Parse(argsJson)![0]!.GetValue<double>();
        return (n * 2).ToString();
    })
    .Build();

use Goplasmatic\Datalogic\Engine;

// 1. Default engine
$engine = new Engine();

// 2. Engine with custom operators via the builder
$engineWithOps = Engine::builder()
    ->addOperator('double', function (string $argsJson): string {
        $args = json_decode($argsJson, true);
        return (string) ((int) $args[0] * 2);
    })
    ->build();

The engine:

• owns the registered custom operators, fixed at build()
• holds the evaluation configuration
• provides the compile and evaluate methods

Operator registration is builder-only. To change a running engine’s operators or configuration, start a builder from it with Engine::to_builder() and build a new engine; the two engines share each operator instance.

Context Stack

The context stack tracks variable scope during evaluation. Iterator operators such as map, filter and reduce push a frame for each element.

// In a filter operation, "" refers to the current element
let r = datalogic_rs::eval_str(
    r#"{"filter": [[1, 2, 3, 4, 5], {">": [{"var": ""}, 3]}]}"#,
    r#"{}"#,
).unwrap();
// Result: "[4,5]"

Inside an iterator body:

• {"var": ""} reads the current element
• val with a level marker ({"val": [[2], "field"]}) reads an enclosing frame or the root (see Variable Access)
• each nested iterator pushes its own frame and pops it when done

Type Coercion

Several operators coerce types:

Arithmetic

• Arithmetic operators parse numeric strings as numbers ("5" + 3 = 8)
• A non-numeric string, including "NaN", "inf" and "infinity", raises a Thrown { type: "NaN" } error by default; change that with EvaluationConfig::arithmetic_nan_handling
• Integers stay exact up to the i64 range: values above 2^53 compare, divide and sort without rounding

Comparison

• == performs loose equality (with type coercion)
• === performs strict equality (no coercion)

Truthiness

By default, the engine uses JavaScript-style truthiness:

• Falsy: false, 0, NaN, "", null, [], {}
• Truthy: everything else

EvaluationConfig::truthy_evaluator changes the rule, and Engine::truthy_of (truthy in the bindings) applies the engine’s rule to a value you already hold.

Thread Safety

Logic is Send + Sync, so you can share it across threads in an Arc:

use datalogic_rs::Engine;
use std::sync::Arc;
use std::thread;

let engine = Arc::new(Engine::new());
let compiled = engine.compile_arc(r#"{"+": [{"var": "x"}, 1]}"#).unwrap();

let handles: Vec<_> = (0..4).map(|i| {
    let engine = Arc::clone(&engine);
    let compiled = Arc::clone(&compiled);
    thread::spawn(move || {
        let mut session = engine.session();
        session.eval_str(&compiled, &format!(r#"{{"x": {}}}"#, i)).unwrap()
    })
}).collect();

for h in handles {
    println!("{}", h.join().unwrap());
}

A Session borrows its engine. To keep a session in a struct field, move it to another thread, or hold it across an .await, use SharedSession, which holds the engine by Arc (SharedSession::new(Arc<Engine>)); see Thread Safety.

Next Steps

• Starter Boilerplates: put compilation and sessions to work in Express, FastAPI, and Axum
• Operators Overview: browse every available operator
• Configuration: customize evaluation behavior, NaN handling, and operator families
• Rule Analysis: validate rules with check and inspect data reads with facts
• Custom Operators: extend the engine with your own host-language logic
• Migration Guide: upgrade from v4 to v5, or from an earlier 5.x release

Starter Boilerplates

Minimal, production-shaped starting points for three web frameworks: route authorization in Express (Node.js), a pricing endpoint in FastAPI (Python), and a feature-flag endpoint in Axum (Rust). Each example compiles its rules once at startup and evaluates them per request.

For full production walkthroughs—including database-backed rule caches, static validation on save, and request-scoped sessions—see Integration: Express and Integration: Spring Boot.

Node.js + Express

Authorize routes with @goplasmatic/datalogic-node middleware. The middleware compiles one rule per route and evaluates it against request properties (here, a role header).

Middleware Implementation

import express from 'express';
import { Engine } from '@goplasmatic/datalogic-node';

const app = express();
const engine = new Engine();

// Authorization rules, as you might load them from a database
const rules = {
  "/admin": { "==": [{ "var": "user.role" }, "admin"] },
  "/billing": { "in": [{ "var": "user.role" }, ["admin", "billing_manager"]] }
};

// Compile each rule once at startup, keyed by route
const compiledRules = {};
for (const [route, rule] of Object.entries(rules)) {
  compiledRules[route] = engine.compile(rule);
}

// Authorization middleware
const authorize = (req, res, next) => {
  const routeRule = compiledRules[req.path];
  if (!routeRule) return next(); // No rule for this route

  // Request context the rule reads
  const context = {
    user: {
      role: req.headers['x-user-role'] || 'guest'
    }
  };

  try {
    const isAllowed = routeRule.evaluate(context); // a JS value: true / false
    if (isAllowed) {
      next();
    } else {
      res.status(403).json({ error: 'Forbidden' });
    }
  } catch (err) {
    res.status(500).json({ error: 'Auth evaluation error' });
  }
};

app.use(authorize);

app.get('/admin', (req, res) => res.send('Welcome, Admin!'));
app.get('/billing', (req, res) => res.send('Billing dashboard'));

Python + FastAPI

Compute a discount at the API boundary with datalogic-py. The same shape works for tax or shipping rules.

Pricing Endpoint

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from datalogic_py import Engine, DataLogicError

app = FastAPI()
engine = Engine()

# Rule: If cart value > 100 AND user is VIP, discount = 20%; otherwise 5%
discount_rule = engine.compile({
    "if": [
        {
            "and": [
                {">": [{"var": "cart_total"}, 100]},
                {"==": [{"var": "user.is_vip"}, True]}
            ]
        },
        0.20,
        0.05
    ]
})

class CartContext(BaseModel):
    cart_total: float
    user: dict  # e.g. {"name": "Alice", "is_vip": True}

@app.post("/calculate-discount")
async def get_discount(context: CartContext):
    try:
        # Evaluate against request data
        discount_percentage = discount_rule.evaluate(context.model_dump())
        return {"discount_percentage": discount_percentage}
    except DataLogicError as e:
        raise HTTPException(status_code=400, detail=f"Rule evaluation failed: {str(e)}")

Rust + Axum

A feature-flag endpoint that compiles its rule at startup and opens a session per request. session.eval_into::<T, _>(...) needs the serde_json feature: datalogic-rs = { version = "5", features = ["serde_json"] }.

use axum::{routing::post, Json, Router};
use datalogic_rs::{Engine, Logic};
use serde::{Deserialize, Serialize};
use std::sync::Arc;

struct AppState {
    engine: Engine,
    rule: Logic,
}

#[derive(Deserialize, Serialize)]
struct UserContext {
    user_id: String,
    country: String,
    beta_user: bool,
}

#[derive(Serialize)]
struct FlagResponse {
    enabled: bool,
}

async fn check_flag(
    axum::extract::State(state): axum::extract::State<Arc<AppState>>,
    Json(payload): Json<UserContext>,
) -> Json<FlagResponse> {
    // A session owns the arena for this request's evaluation
    let mut session = state.engine.session();

    // An evaluation error counts as "flag off"
    let result = session.eval_into::<bool, _>(
        &state.rule,
        &serde_json::to_value(payload).unwrap()
    ).unwrap_or(false);

    Json(FlagResponse { enabled: result })
}

#[tokio::main]
async fn main() {
    let engine = Engine::new();
    // Rule: enable the beta feature for beta users or users in CA
    let rule = engine.compile(r#"{
        "or": [
            {"==": [{"var": "beta_user"}, true]},
            {"==": [{"var": "country"}, "CA"]}
        ]
    }"#).unwrap();

    let state = Arc::new(AppState { engine, rule });

    let app = Router::new()
        .route("/flag", post(check_flag))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Next Steps

• Full service integrations: Integration: Express and Integration: Spring Boot
• Language guides: Node.js, Python, Rust, Go, Java / Kotlin, .NET, PHP
• Production hardening: Thread Safety, Rule Analysis (check & facts), Operation Budget, and Security & Sandboxing

Operators Overview

datalogic-rs provides 84 built-in operators organized into logical categories. In the Rust crate, 33 baseline operators are always available in the default build (default = []); a further 29 canonical operators are enabled by opt-in Cargo features, twenty tensor-marshalling operators sit behind the tensor feature, and two flagd-compatible operators (fractional, sem_ver) sit behind the flagd feature. Every language binding (WASM, Node, Python, Go, JVM, .NET, PHP) ships with all operator features enabled, so outside Rust the full set is available with no configuration. Counts are by canonical operator: var and ?: are accepted as input aliases of val and if, and match is an alias of switch, so the aliases are not counted separately. Each page in this section gives an operator’s syntax, argument counts, examples and edge cases.

Operator Categories

Which operators need which Cargo feature

The split applies to the Rust crate. The default build (default = []) compiles in the baseline only, and the all-operators feature turns on every family below at once. A rule that names an operator your build left out still compiles: Engine::compile treats the unknown key like an unregistered custom operator, and evaluating the rule fails with an InvalidOperator error naming the operator. Engine::check and Engine::compile_checked report the unknown operator before the rule runs. In templating mode the engine echoes an unknown key as data instead (see Structured Objects). Every language binding enables all operator features, so the full set is available there.

tensor-half adds no operators; it lets the element-wise tensor operators handle f16 / bf16.

The table above is generated from the engine’s operator table (UPDATE_OPERATORS_JSON=1 cargo test -p datalogic-rs --all-features --test operators_json_test regenerates it, together with operators.json).

Operator families

Each row of the table is one operator family: Core (the baseline), DateTime, ExtString, ExtArray, ExtObject, ExtControl, ErrorHandling, ExtMath, Tensor and Flagd, in table order. Since 5.8.0 you can also keep one engine to a subset of the families its build compiled in:

use datalogic_rs::{Engine, Family};

// The JSONLogic core plus the string extensions.
let engine = Engine::builder().with_families([Family::ExtString]).build();

On that engine a family you left out behaves like one the build never compiled, and Core is always present. The bindings take the same option as a list of family names (families, Families, withFamilies or WithFamilies). See Operator Families.

Operator catalogue

Engine::operators() describes every built-in operator an engine has: canonical name and aliases, family and Cargo feature, the argument counts it reads (min_args, and max_args or no upper limit), whether it reads the data context, its effect (pure, clock, throws, catches), its cost class, and which argument runs under a pushed frame. operators.json is that catalogue for an all-operators build, and the bindings return the same JSON from their operators call. Engine::builtin_operator_names() lists the names alone, aliases included. Both follow the engine’s families, so use them instead of a hand-copied list when tooling needs to know what an engine evaluates. Rule Analysis covers the catalogue API and its fields.

An argument past max_args is never evaluated. Most operators ignore it; length, the tensor operators and the JSONLogic iterators (filter, map, reduce, all, some, none) reject it, and sem_ver returns null.

Operator Syntax

All operators follow the JSONLogic format:

{ "operator": [arg1, arg2, ...] }

Some operators accept a single argument without an array:

{ "var": "name" }
// Equivalent to:
{ "var": ["name"] }

Lazy Evaluation

These operators evaluate an argument only when they need it:

• and: stops at the first falsy value
• or: stops at the first truthy value
• if (and its alias ?:): evaluates only the matching branch
• ??: stops at the first value that is not null
• switch (and its alias match): evaluates only the matching case’s result, or the default
• try: evaluates a fallback arm only if every arm before it raised an error

This matters when a later operand could raise an error, or is expensive:

{
  "and": [
    { "var": "denominator" },
    { "/": [100, { "var": "denominator" }] }
  ]
}

If denominator is missing or 0, and returns that falsy value and never evaluates the division (which would throw a NaN error for an integer zero divisor); with { "denominator": 4 } the result is 25. Under the default configuration var returns null for a missing path, so plain property access such as { "var": "user.profile.name" } needs no guard; an engine configured with MissingVar::Error raises VariableNotFound for it instead (see Missing Variables).

Type Coercion

Loose vs Strict

• == and != perform type coercion
• === and !== require exact type match

{ "==": [1, "1"] }   // true (loose)
{ "===": [1, "1"] }  // false (strict)

Numeric Coercion

Arithmetic operators attempt to convert values to numbers:

{ "+": ["5", 3] }  // 8 (string "5" becomes number 5)

Truthiness

Boolean operators use configurable truthiness rules (see Truthiness Evaluation). Under the default, TruthyEvaluator::JavaScript:

• Falsy: false, 0, "", null, [], {}
• Truthy: everything else

Custom Operators

You register your own operators on the engine builder. See Custom Operators for details.

let engine = Engine::builder()
    .add_operator("myop", MyOperator)
    .build();

Custom operators follow the same syntax in rules:

{ "myop": [arg1, arg2] }

A custom operator registered under the name of a built-in the engine has never runs, because the built-in wins at compile time. EngineBuilder::try_add_operator refuses such a name with a ConfigurationError.

There is no preserve operator. To emit a JSON object verbatim from a rule, use templating mode (Engine::builder().with_templating(true).build(), Cargo feature templating). Literal scalars and arrays work inline in every mode.

Emitting a key that is an operator name. Because a single-key object is an operator invocation, {"type": {"var": "x"}} runs the type operator rather than emitting a type field, and the same applies to every name on this page plus any custom operator you register. In templating mode you can opt into an escape prefix, Engine::builder().with_template_key_escape('$'), and write {"$type": ...} to emit type ({"$$type": ...} emits a literal $type). See Structured Objects.

Variable Access Operators

These operators access data from the evaluation context.

Feature flags (Rust crate). var and val are baseline; exists requires the ext-control feature. Every language binding enables all operator features. An engine built with EngineBuilder::with_families has exists only if it names Family::ExtControl. See the feature table.

var

Access a value from the data object using dot notation.

Syntax:

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

Arguments:

• path - Dot-separated path to the value (a string, a number, or an expression that produces one)
• default - Optional value returned when the path does not exist

Returns: The value at the path, or the default value, or null.

Examples:

// Simple access
{ "var": "name" }
// Data: { "name": "Alice" }
// Result: "Alice"

// Nested access
{ "var": "user.address.city" }
// Data: { "user": { "address": { "city": "NYC" } } }
// Result: "NYC"

// Array index access
{ "var": "items.0" }
// Data: { "items": ["a", "b", "c"] }
// Result: "a"

// Default value
{ "var": ["missing", "default"] }
// Data: {}
// Result: "default"

// Access entire data object
{ "var": "" }
// Data: { "x": 1, "y": 2 }
// Result: { "x": 1, "y": 2 }

Try it:

Notes:

• Empty string "" returns the entire data context
• In array operations (map, filter, reduce), "" refers to the current element
• Numeric segments index arrays (items.0); strings are not indexable, so { "var": "s.1" } on { "s": "hello" } is null. Use substr to read characters
• A literal path always splits on dots, so { "var": "a.b" } cannot read a key named "a.b"; use { "val": "a.b" } for that. A path computed at runtime ({ "var": { "cat": ["a", ".b"] } }) is looked up as a key first and walked as a dotted path only if no such key exists
• The default applies only when the path is absent: a present null stays null
• Returns null if the path doesn’t exist and no default is provided, or raises an error under MissingVar::Error (see Missing paths)

val

Alternative variable access with explicit path segments and scope levels.

Syntax:

{ "val": "key" }
{ "val": ["segment1", "segment2", ...] }
{ "val": [[N], "segment1", ...] }
{ "val": [] }

Arguments:

• key - A single literal key (string)
• ["segment1", "segment2", ...] - Path segments walked in order. Every array element is one segment (a string key or a numeric array index); there is no default-value slot
• [[N], ...] - An optional leading scope level for iteration frames (see Scope levels below)
• [] - No segments: returns the current context (the whole data object, or the current element inside an iterator)

Returns: The value at the path, or null if any segment is missing. val has no default argument: use var’s second argument or ?? for a fallback.

Examples:

// Simple access (same as var)
{ "val": "name" }
// Data: { "name": "Bob" }
// Result: "Bob"

// Nested access (use the array form; a dot string is NOT split)
{ "val": ["config", "settings", "enabled"] }
// Data: { "config": { "settings": { "enabled": true } } }
// Result: true

// A dot-path string is treated as a single literal key, so it does NOT navigate
{ "val": "config.settings.enabled" }
// Data: { "config": { "settings": { "enabled": true } } }
// Result: null (looks up the key "config.settings.enabled", which is absent)

// Numeric segments index arrays
{ "val": ["items", 0] }
// Data: { "items": ["a", "b"] }
// Result: "a"

// No default slot: a second element is another path segment
{ "val": ["missing", "default"] }
// Data: {}
// Result: null (looks up data.missing.default)

// Fallbacks use ?? (or var's default form) instead
{ "??": [{ "val": ["missing", "key"] }, "default"] }
// Data: {}
// Result: "default"

Try it:

Notes:

• A literal string argument is a single key, so { "val": "a.b" } looks up the key "a.b"; it does not descend into a then b
• For nested access use the array form { "val": ["a", "b"] }, where each element is one path segment
• There is no [path, default] form: { "val": ["a", "b"] } always walks a then b. Use { "var": ["a", "default"] } or { "??": [{ "val": "a" }, "default"] } for a fallback. Under MissingVar::Error the ?? form raises; see Missing paths
• A string computed at runtime is read the way var reads a computed path: { "val": { "cat": ["a", ".b"] } } reads the key "a.b" if present, otherwise a then b. In the array form, a computed segment containing dots is walked as a dotted path
• Logic::to_json() writes a dotted val key back as { "val": "a.b" }, so the serialized rule reads the same key

Scope levels

Inside an iterator (map, filter, all, some, none, group_by, and the per-element expressions of sort, distinct, and reduce) the current element is the data context, so { "val": "field" } reads the element. A leading [N] array selects a different frame. This is the only way to reach an enclosing iterator’s element, or iteration metadata (the element’s index or key).

Syntax:

{ "val": [] }
{ "val": [[1], "index"] }
{ "val": [[1], "key"] }
{ "val": [[N]] }
{ "val": [[N], "segment1", "segment2", ...] }

Levels come in pairs, because the reference implementation this form comes from keeps two entries per iterator: the iteration metadata, then the enclosing element. [[1]] and [[2]] therefore name the same frame, one iterator out; [[3]] and [[4]] name the one beyond it, and so on. Levels count frames, not iterators of a particular kind: a reduce body and a try catch arm each consume a level exactly like a map body.

• { "val": [] } returns the current element itself (same as { "var": "" }).
• { "val": [[N]] } and { "val": [[N], "field", ...] } read data from the frame ceil(N / 2) iterators out: [[1]]/[[2]] is the enclosing element, [[3]]/[[4]] the one outside that. A level that climbs past the outermost frame resolves against the root data, so from inside a single iterator [[1], "field"] and every higher level read the root.
• { "val": [[1], "index"] } returns the current element’s zero-based position while iterating an array (or an object, in stored order); { "val": [[1], "key"] } returns its key while iterating an object. [[3]] reads the enclosing iterator’s index or key, [[5]] the one beyond it. Only odd levels work, since an even level names an element rather than its metadata.
• index and key are null wherever no such metadata exists: key over an array, anything inside reduce or a try catch arm (those frames carry no iteration metadata), and a level that climbs past the outermost frame. At an even level they are ordinary field names, so { "val": [[2], "index"] } reads a field called index on the enclosing element.
• The sign is ignored: [[-2]] and [[2]] are the same level.
• A marker is an array of exactly one number. { "val": [[0, 1]] } is a path chain walking index 0 then index 1, not level 0 with a stray tail, and { "val": [[2, 9], "field"] } is not level 2.
• Relative path syntax such as "../field" is not supported; the engine treats it as a literal key, which resolves to null.
• var accepts the same [[N], ...] form, because it compiles to val.

Reading an enclosing element from a nested iterator:

{
  "map": [
    { "val": "orders" },
    { "map": [
      { "val": "lines" },
      { "*": [{ "val": "qty" }, { "val": [[2], "rate"] }] }
    ]}
  ]
}

[[2]] leaves the inner map and reads rate from the order; [[3], "index"] would give the order’s position, and [[4], "field"] the root data.

Differences from json-logic-engine. datalogic follows that engine for every level it resolves, with three exceptions, each returning a value where that engine returns null:

It also stops resolving past the fourth chain entry, where datalogic keeps climbing.

Examples:

// Pair each element with its index
{ "map": [{ "var": "items" }, { "cat": [{ "val": [[1], "index"] }, ":", { "var": "" }] }] }
// Data: { "items": ["a", "b"] }
// Result: ["0:a", "1:b"]

// Keep every element except the first
{ "filter": [[10, 20, 30], { ">": [{ "val": [[1], "index"] }, 0] }] }
// Result: [20, 30]

// Object iteration exposes the key
{ "map": [{ "var": "scores" }, { "val": [[1], "key"] }] }
// Data: { "scores": { "alice": 10, "bob": 7 } }
// Result: ["alice", "bob"]

// Compare each element against a root-level value
{ "filter": [
    { "var": "people" },
    { "==": [{ "val": "department" }, { "val": [[2], "department"] }] }
]}
// Data: {
//   "department": "Engineering",
//   "people": [
//     { "name": "Jay", "department": "Engineering" },
//     { "name": "Louisa", "department": "Sales" }
//   ]
// }
// Result: [{ "name": "Jay", "department": "Engineering" }]

// Add a root value to each element
{ "map": [{ "var": "numbers" }, { "+": [{ "val": [[2], "offset"] }, { "val": [] }] }] }
// Data: { "numbers": [1, 2, 3], "offset": 10 }
// Result: [11, 12, 13]

exists

Check if a variable path exists in the data.

Syntax:

{ "exists": "key" }
{ "exists": ["key1", "key2", ...] }
{ "exists": { "var": "path" } }

Arguments:

• key - A single top-level key (string), or
• ["key1", "key2", ...] - An array of object keys walked in order for nested access, or
• A var operation that resolves to the key/path to check

Returns: true if the path exists, false otherwise.

Examples:

// Check if key exists
{ "exists": "name" }
// Data: { "name": "Alice" }
// Result: true

// Check missing key
{ "exists": "age" }
// Data: { "name": "Alice" }
// Result: false

// Check nested path (use the array form; a dot string is one literal key)
{ "exists": ["user", "profile"] }
// Data: { "user": { "profile": { "name": "Bob" } } }
// Result: true

// A dot-path string checks a single literal key, so it does not descend
{ "exists": "user.profile" }
// Data: { "user": { "profile": { "name": "Bob" } } }
// Result: false (no top-level key named "user.profile")

// Check with var
{ "exists": { "var": "fieldName" } }
// Data: { "fieldName": "name", "name": "Alice" }
// Result: true (checks if "name" exists)

Try it:

Notes:

• Checks only whether the path exists: a key holding null or "" exists
• Segments must be object keys: exists does not index arrays, so { "exists": ["items", 0] } is false even though { "val": ["items", 0] } resolves. Test array elements with { "!==": [{ "val": ["items", 0] }, null] } or length instead
• An empty segment list, { "exists": [] }, returns true

Missing paths

A var or val read whose path is absent evaluates to null, as JSONLogic specifies. An engine whose EvaluationConfig::missing_var is MissingVar::Error raises a VariableNotFound error naming the path instead, so a misspelled path fails rather than producing null:

{ "var": "user.nmae" }
// Data: { "user": { "name": "Ana" } }
// Result: null (default)
// Under MissingVar::Error: VariableNotFound error naming "user.nmae"

These are not misses, and evaluate the same under both settings:

• a var with a default: { "var": ["x", 0] } on {} is 0
• a path that is present and holds null
• { "var": "" } and { "val": [] }, the current data
• iteration metadata ({ "val": [[1], "index"] }), which is null outside an iterator
• missing, missing_some and exists, which report absence

?? does not shield a miss, because its operand raises before ?? sees a value. Use var’s default, or try ({ "try": [{ "var": "x" }, "fallback"] }), which catches the error like any other. The language bindings take the setting as "missing_var": "error" in their JSON config. See Missing Variables.

See Also

• Missing Value Operators (missing, missing_some): check whether required fields are present
• Array Operators: iterate over arrays with map, filter, and reduce using scope levels
• Control Flow (??): null-coalescing fallbacks
• Rule Analysis (facts): inspect all root data paths a compiled rule reads
• Operators Overview: full operator table and feature flags

Comparison Operators

Operators for comparing values. ==, === and the ordering operators take two or more operands and stop at the first comparison that fails, leaving later operands unevaluated. != and !== take exactly two.

Numbers compare by value, and two integers compare exactly, also above 2^53 ({ "===": [9007199254740993, 9007199254740992] } is false). With the datetime feature, two datetimes compare as instants and two durations by length, whether written as strings or as { "datetime": ... } / { "timestamp": ... } values: { "==": ["2024-01-01T00:00:00Z", "2024-01-01T00:00:00+00:00"] } is true. Only a single-key { "datetime": ... } or { "timestamp": ... } object counts as one; a record that also has other fields is ordinary data.

Feature flags (Rust crate). All comparison operators are baseline: every build has them. See the feature table.

== (Equals)

Loose equality comparison with type coercion.

Syntax:

{ "==": [a, b] }
{ "==": [a, b, c, ...] }

Arguments:

• a, b - Values to compare
• c, … - Optional further values; each must equal a

Returns: true if every value equals the first (after type coercion), false otherwise.

Examples:

// Same type
{ "==": [1, 1] }
// Result: true

// Type coercion
{ "==": [1, "1"] }
// Result: true

{ "==": [0, false] }
// Result: true

{ "==": ["", false] }
// Result: false (a String and a Bool are compared as strings, with no JS numeric coercion)

// Null comparison
{ "==": [null, null] }
// Result: true

// Arrays
{ "==": [[1, 2], [1, 2]] }
// Result: true

// More than two operands
{ "==": [1, "1", 1.0] }
// Result: true

Try it:

Coercion rules:

These rules differ from JavaScript’s ==: { "==": [null, 0] } is true here.

Operands that cannot be compared are an error by default (error type NaN): a number against a string that is not a finite number ({ "==": [1, "abc"] }, { "==": [1, "NaN"] }), an array or object against a scalar ({ "==": [1, [1]] }), and two arrays that differ. Set EvaluationConfig::loose_equality_errors to false to get false instead (see Loose Equality Errors). For comparison without coercion, use ===.

=== (Strict Equals)

Strict equality comparison without type coercion.

Syntax:

{ "===": [a, b] }
{ "===": [a, b, c, ...] }

Arguments:

• a, b - Values to compare
• c, … - Optional further values; each must equal a

Returns: true if every value has the same type and value as the first, false otherwise.

Examples:

// Same type and value
{ "===": [1, 1] }
// Result: true

// Different types
{ "===": [1, "1"] }
// Result: false

{ "===": [0, false] }
// Result: false

// Null
{ "===": [null, null] }
// Result: true

// An integer and a float with the same value
{ "===": [1, 1.0] }
// Result: true

Try it:

Notes:

• Arrays and objects compare by content: two objects with the same keys and values are equal
• === never raises an error for mismatched types; it returns false

!= (Not Equals)

Loose inequality comparison with type coercion.

Syntax:

{ "!=": [a, b] }

Arguments:

• a - First value
• b - Second value

Returns: true if values are not equal (after type coercion), false otherwise. The negation of ==, with the same coercion rules and errors.

Examples:

{ "!=": [1, 2] }
// Result: true

{ "!=": [1, "1"] }
// Result: false (type coercion makes them equal)

{ "!=": ["hello", "world"] }
// Result: true

Try it:

Notes (!=, !==):

• Exactly two operands are compared. Further operands are ignored and never evaluated: { "!=": [1, 1, 2] } is false
• Fewer than two operands is an Invalid Arguments error

!== (Strict Not Equals)

Strict inequality comparison without type coercion.

Syntax:

{ "!==": [a, b] }

Arguments:

• a - First value
• b - Second value

Returns: true if values are not equal or different types, false otherwise. The negation of ===.

Examples:

{ "!==": [1, "1"] }
// Result: true (different types)

{ "!==": [1, 1] }
// Result: false

{ "!==": [1, 2] }
// Result: true

> (Greater Than)

Check if the first value is greater than the second.

Syntax:

{ ">": [a, b] }
{ ">": [a, b, c, ...] }

Arguments:

• a, b - Values to compare
• c, … - Optional further values for chained comparison (any number)

Returns: true if a > b (and b > c if provided), false otherwise.

Examples:

// Simple comparison
{ ">": [5, 3] }
// Result: true

{ ">": [3, 5] }
// Result: false

// Chained comparison (a > b > c)
{ ">": [5, 3, 1] }
// Result: true (5 > 3 AND 3 > 1)

{ ">": [5, 3, 4] }
// Result: false (3 is not > 4)

// String comparison
{ ">": ["b", "a"] }
// Result: true (lexicographic)

// With variables
{ ">": [{ "var": "age" }, 18] }
// Data: { "age": 21 }
// Result: true

Try it:

>= (Greater Than or Equal)

Check if the first value is greater than or equal to the second.

Syntax:

{ ">=": [a, b] }
{ ">=": [a, b, c, ...] }

Arguments:

• a, b - Values to compare
• c, … - Optional further values for chained comparison (any number)

Returns: true if a >= b (and b >= c if provided), false otherwise.

Examples:

{ ">=": [5, 5] }
// Result: true

{ ">=": [5, 3] }
// Result: true

{ ">=": [3, 5] }
// Result: false

// Chained
{ ">=": [5, 3, 3] }
// Result: true (5 >= 3 AND 3 >= 3)

< (Less Than)

Check if the first value is less than the second.

Syntax:

{ "<": [a, b] }
{ "<": [a, b, c, ...] }

Arguments:

• a, b - Values to compare
• c, … - Optional further values for chained comparison (any number)

Returns: true if a < b (and b < c if provided), false otherwise.

Examples:

{ "<": [3, 5] }
// Result: true

{ "<": [5, 3] }
// Result: false

// Chained (useful for range checks)
{ "<": [1, 5, 10] }
// Result: true (1 < 5 AND 5 < 10)

// Range check: is x between 1 and 10?
{ "<": [1, { "var": "x" }, 10] }
// Data: { "x": 5 }
// Result: true

Try it:

<= (Less Than or Equal)

Check if the first value is less than or equal to the second.

Syntax:

{ "<=": [a, b] }
{ "<=": [a, b, c, ...] }

Arguments:

• a, b - Values to compare
• c, … - Optional further values for chained comparison (any number)

Returns: true if a <= b (and b <= c if provided), false otherwise.

Examples:

{ "<=": [3, 5] }
// Result: true

{ "<=": [5, 5] }
// Result: true

{ "<=": [5, 3] }
// Result: false

// Range check (inclusive)
{ "<=": [1, { "var": "x" }, 10] }
// Data: { "x": 10 }
// Result: true (1 <= 10 AND 10 <= 10)

Notes (all ordering operators):

• { "<": [a, x, b] } is equivalent to a < x AND x < b, which suits range checks
• The operators accept any number of operands: { "<": [1, 2, 3, 4] } is true and { "<": [1, 2, 5, 4] } is false. Evaluation short-circuits at the first failing pair and never evaluates later operands ({ ">": [5, 3, 4, { "throw": "boom" }] } is false, nothing is thrown)
• Fewer than two operands ({ "<": [1] }, { "<": [] }) is an Invalid Arguments error
• Two strings compare lexicographically ({ ">": ["10", "9"] } is false); a string against a number is coerced numerically ({ ">": ["10", 9] } is true). A string that is not a finite number against a number throws a NaN error ({ "<": ["abc", 1] }, { "<": [1, "inf"] })
• null and booleans compare as numbers ({ "<": [null, 1] } and { "<": [false, true] } are true)
• An array or object operand (other than a datetime or duration value) throws a NaN error

See Also

• Logical Operators (!, !!, and, or): combine comparison results
• Control Flow (if, ?:, switch): branch on comparisons
• DateTime Operators: compare ISO 8601 instants and durations
• Configuration: Loose Equality Errors: customize how == and != handle incomparable types
• Operators Overview: full operator table and feature flags

Logical Operators

Boolean logic operators. and and or short-circuit: they stop at the first operand that decides the result and leave the rest unevaluated.

Feature flags (Rust crate). All logical operators are baseline: every build has them. See the feature table.

! (Not)

Logical NOT: negates the truthiness of a value.

Syntax:

{ "!": value }
{ "!": [value] }

Arguments:

• value - Value to negate

Returns: true if value is falsy, false if value is truthy.

Examples:

{ "!": true }
// Result: false

{ "!": false }
// Result: true

{ "!": 0 }
// Result: true (0 is falsy)

{ "!": 1 }
// Result: false (1 is truthy)

{ "!": "" }
// Result: true (empty string is falsy)

{ "!": "hello" }
// Result: false (non-empty string is truthy)

{ "!": null }
// Result: true (null is falsy)

{ "!": [] }
// Result: true (no argument, treated as null)

// An array argument is the argument list: only the first element is negated
{ "!": [0, 2] }
// Result: true (negates 0; the 2 is ignored)

// To negate a literal array, wrap it so the array is the single argument
{ "!": [[1, 2]] }
// Result: false (non-empty array is truthy)

Try it:

Notes:

• Uses the engine’s truthiness rules (default: JavaScript-style; see Truthiness Reference)
• An array argument is read as the argument list, and ! uses only its first element. To negate a literal array, wrap it: { "!": [[1, 2]] }

!! (Double Not / Boolean Cast)

Convert a value to its boolean equivalent.

Syntax:

{ "!!": value }
{ "!!": [value] }

Arguments:

• value - Value to convert to boolean

Returns: true if value is truthy, false if value is falsy.

Examples:

{ "!!": true }
// Result: true

{ "!!": false }
// Result: false

{ "!!": 1 }
// Result: true

{ "!!": 0 }
// Result: false

{ "!!": "hello" }
// Result: true

{ "!!": "" }
// Result: false

// A literal array must be wrapped so it is the single argument
{ "!!": [[1, 2, 3]] }
// Result: true

{ "!!": [] }
// Result: false

// Unwrapped, the array is the argument list and only the first element counts
{ "!!": [0, 2, 3] }
// Result: false

{ "!!": null }
// Result: false

Try it:

Notes:

• Equivalent to { "!": { "!": value } }; use it to turn any value into a boolean
• Like !, an array argument is the argument list and only its first element is inspected; wrap a literal array ({ "!!": [[]] } is false, { "!!": [{}] } is false)

and

Logical AND with short-circuit evaluation.

Syntax:

{ "and": [a, b, ...] }

Arguments:

• a, b, … - One or more values to AND together, always passed as an array. A single-element array returns that element; an empty array returns null; a bare scalar ({ "and": 5 }) is an Invalid Arguments error

Returns: The first falsy value encountered, or the last value if all are truthy.

Examples:

// All truthy
{ "and": [true, true] }
// Result: true

// One falsy
{ "and": [true, false] }
// Result: false

// Short-circuit: returns first falsy
{ "and": [true, 0, "never evaluated"] }
// Result: 0

// All truthy returns last value
{ "and": [1, 2, 3] }
// Result: 3

// Multiple conditions
{ "and": [
    { ">": [{ "var": "age" }, 18] },
    { "==": [{ "var": "verified" }, true] },
    { "!=": [{ "var": "banned" }, true] }
]}
// Data: { "age": 21, "verified": true, "banned": false }
// Result: true

Try it:

Notes:

• Short-circuits: stops at the first falsy value
• Returns the operand itself, which need not be a boolean

or

Logical OR with short-circuit evaluation.

Syntax:

{ "or": [a, b, ...] }

Arguments:

• a, b, … - One or more values to OR together, always passed as an array. A single-element array returns that element; an empty array returns null; a bare scalar ({ "or": "x" }) is an Invalid Arguments error

Returns: The first truthy value encountered, or the last value if all are falsy.

Examples:

// One truthy
{ "or": [false, true] }
// Result: true

// All falsy
{ "or": [false, false] }
// Result: false

// Short-circuit: returns first truthy
{ "or": [0, "", "found it", "not evaluated"] }
// Result: "found it"

// All falsy returns last value
{ "or": [false, 0, ""] }
// Result: ""

// Default value pattern
{ "or": [{ "var": "nickname" }, { "var": "name" }, "Anonymous"] }
// Data: { "name": "Alice" }
// Result: "Alice" (nickname is null/missing, so returns name)

// Role check
{ "or": [
    { "==": [{ "var": "role" }, "admin"] },
    { "==": [{ "var": "role" }, "moderator"] }
]}
// Data: { "role": "admin" }
// Result: true

Try it:

Notes:

• Short-circuits: stops at the first truthy value
• Returns the operand itself, which need not be a boolean, so or can supply a default value

Truthiness Reference

The default JavaScript-style truthiness:

EvaluationConfig::truthy_evaluator replaces these rules wherever an operator tests truthiness (!, !!, and, or, if, and the conditions of filter, all, some and none); see Truthiness Evaluation. To apply the engine’s rules to a value in host code, such as an evaluated result, call Engine::truthy_of.

See Also

• Control Flow (if, ?:, ??, switch): conditional branching and null-coalescing
• Comparison Operators (==, ===, >, <): equality and ordering checks
• Array Operators (all, some, none): test conditions across collections
• Operators Overview: full operator table and feature flags

Arithmetic Operators

Mathematical operations. +, -, *, / and % read numeric strings, booleans and null as numbers (see Non-numeric operands); abs, ceil and floor accept numbers and numeric strings; max and min accept numbers only. Integer arithmetic stays exact, also above 2^53, until a result overflows i64, where it continues as a float.

With the datetime feature, +, -, * and / also take datetimes and durations; see Duration Arithmetic.

Feature flags (Rust crate). +, -, *, /, %, min, and max are baseline; abs, ceil, and floor require the ext-math feature. Every language binding enables all operator features. An engine built with EngineBuilder::with_families has abs, ceil and floor only if it names Family::ExtMath. See the feature table.

+ (Add)

Add numbers together (numeric strings are coerced).

Syntax:

{ "+": [a, b, ...] }
{ "+": value }

Arguments:

• a, b, … - Values to add (variadic)
• value - A single operand is converted to a number. If it evaluates to an array (from var, for example), + sums the elements; a literal array written in the rule is a non-numeric operand (a NaN error by default)

Returns: Sum of all arguments.

Examples:

// Basic addition
{ "+": [1, 2] }
// Result: 3

// Multiple values
{ "+": [1, 2, 3, 4] }
// Result: 10

// Type coercion
{ "+": ["5", 3] }
// Result: 8 (string "5" converted to number)

{ "+": ["1", "2", "3"] }
// Result: 6

// Unary plus (convert to number)
{ "+": "42" }
// Result: 42

{ "+": "-3.14" }
// Result: -3.14

// With variables
{ "+": [{ "var": "price" }, { "var": "tax" }] }
// Data: { "price": 100, "tax": 8.5 }
// Result: 108.5

// Sum an array from the data
{ "+": { "var": "items" } }
// Data: { "items": [1, 2, 3] }
// Result: 6

Try it:

Notes:

• + never concatenates: { "+": ["hello", " world"] } is a NaN error under the default EvaluationConfig::arithmetic_nan_handling. Use cat to join strings
• { "+": [] } returns 0
• An integer sum that overflows i64 continues as a float: { "+": [9223372036854775807, 1] } is 9.223372036854776e18

- (Subtract)

Subtract numbers.

Syntax:

{ "-": [a, b] }
{ "-": [a, b, c, ...] }
{ "-": value }

Arguments:

• a - Value to subtract from
• b, c, … - Values to subtract, folded left to right (a - b - c ...)
• value - A single operand is negated. If it evaluates to an array, - folds over the elements ({ "-": [[10, 3]] } is 7)

Returns: Difference, or negated value. An empty argument list, or a single operand that is an empty array, is an Invalid Arguments error.

Examples:

// Subtraction
{ "-": [10, 3] }
// Result: 7

// Unary minus (negate)
{ "-": 5 }
// Result: -5

{ "-": -3 }
// Result: 3

// With coercion
{ "-": ["10", "3"] }
// Result: 7

// Variadic (left fold)
{ "-": [10, 3, 2] }
// Result: 5

// Calculate discount
{ "-": [{ "var": "price" }, { "var": "discount" }] }
// Data: { "price": 100, "discount": 15 }
// Result: 85

Try it:

* (Multiply)

Multiply numbers.

Syntax:

{ "*": [a, b, ...] }
{ "*": value }

Arguments:

• a, b, … - Values to multiply (variadic)
• value - A single operand is converted to a number. If it evaluates to an array, * multiplies the elements; a literal array written in the rule is a non-numeric operand (a NaN error by default)

Returns: Product of all arguments. { "*": [] } returns 1.

Examples:

// Basic multiplication
{ "*": [3, 4] }
// Result: 12

// Multiple values
{ "*": [2, 3, 4] }
// Result: 24

// With coercion
{ "*": ["5", 2] }
// Result: 10

{ "*": ["2", "3", "4"] }
// Result: 24

// Calculate total
{ "*": [{ "var": "quantity" }, { "var": "price" }] }
// Data: { "quantity": 3, "price": 25 }
// Result: 75

// Apply percentage
{ "*": [{ "var": "amount" }, 0.1] }
// Data: { "amount": 200 }
// Result: 20

Try it:

/ (Divide)

Divide numbers.

Syntax:

{ "/": [a, b] }
{ "/": [a, b, c, ...] }
{ "/": value }

Arguments:

• a - Dividend
• b, c, … - Divisors, folded left to right (a / b / c ...)
• value - A single operand returns its reciprocal (1 / value). If it evaluates to an array, / folds over the elements ({ "/": [[100, 2, 5]] } is 10)

Returns: Quotient, or the reciprocal for the single-value form. Integer operands divide exactly: a whole quotient stays an integer, also above 2^53 ({ "/": [18014398509481988, 2] } is 9007199254740994).

Examples:

// Basic division
{ "/": [10, 2] }
// Result: 5

// Decimal result
{ "/": [7, 2] }
// Result: 3.5

// Division by zero with two integral-valued operands throws an error (error type "NaN")
{ "/": [10, 0] }
// Result: error

// Variadic (left fold)
{ "/": [100, 2, 5] }
// Result: 10

// Unary form: reciprocal
{ "/": 5 }
// Result: 0.2

// With coercion
{ "/": ["100", "4"] }
// Result: 25

// Calculate average
{ "/": [{ "+": [10, 20, 30] }, 3] }
// Result: 20

Try it:

Notes:

• If both operands are integral-valued numbers and the divisor is zero ({ "/": [10, 0] }, and also { "/": [10, 0.0] }, since 0.0 is integral-valued), the engine throws a NaN error under every configuration. A single zero operand ({ "/": 0 }) is a NaN error too
• Any other zero divisor follows EvaluationConfig::division_by_zero: a non-integral dividend ({ "/": [10.5, 0] }) or a divisor coerced from null, a boolean, or a string ({ "/": [10, null] }, { "/": [10, "0"] }). The default, DivisionByZeroHandling::ReturnSaturated, returns f64::MAX (f64::MIN for a negative dividend) instead of Infinity
• The other modes are ReturnInfinity, ReturnNull and ThrowError (see Division by Zero). Choose ThrowError if a try fallback should cover every zero-like divisor

% (Modulo)

Calculate remainder of division.

Syntax:

{ "%": [a, b] }
{ "%": [a, b, c, ...] }

Arguments:

• a - Dividend
• b, c, … - Divisors, folded left to right ((a % b) % c ...)

Returns: Remainder after division, with the sign of the dividend. Integers stay exact above 2^53. A single operand must evaluate to an array of at least two numbers, which % folds ({ "%": [[10, 4]] } is 2); any other single operand is an Invalid Arguments error.

Examples:

// Basic modulo
{ "%": [10, 3] }
// Result: 1

{ "%": [10, 5] }
// Result: 0

// Negative numbers
{ "%": [-10, 3] }
// Result: -1

// Check if even
{ "==": [{ "%": [{ "var": "n" }, 2] }, 0] }
// Data: { "n": 4 }
// Result: true

Try it:

Notes:

• A zero divisor follows the same rule as /: when both operands are integral-valued numbers ({ "%": [10, 0] }) the engine throws a NaN error; otherwise ({ "%": [10.5, 0] }, { "%": [10, null] }) the result follows EvaluationConfig::division_by_zero, default ReturnSaturated

max

Find the maximum value.

Syntax:

{ "max": [a, b, ...] }
{ "max": array }

Arguments:

• a, b, … - Values to compare, or
• array - A single value (such as a var) that resolves to an array. It must be a resolved array, not a literal array written inline

Returns: The largest value.

Examples:

// Multiple arguments
{ "max": [1, 5, 3] }
// Result: 5

// A single argument that resolves to an array (data-driven)
{ "max": { "var": "scores" } }
// Data: { "scores": [85, 92, 78] }
// Result: 92

// Note: a literal nested array passed positionally, e.g. { "max": [[1, 5, 3]] }
// or { "max": [[]] }, is an invalid operand and throws Invalid Arguments.
// Pass scalars directly, or a value that resolves to an array.

Try it:

Notes:

• Operands must be numbers. max does not coerce strings (even numeric ones such as "1"), booleans, or null; they throw Invalid Arguments. This differs from json-logic-js, which coerces { "max": ["1", 5, "3"] } to 5
• An empty argument list, or a single value that resolves to an empty array, throws Invalid Arguments

min

Find the minimum value.

Syntax:

{ "min": [a, b, ...] }
{ "min": array }

Arguments:

• a, b, … - Values to compare, or
• array - A single value (such as a var) that resolves to an array. It must be a resolved array, not a literal array written inline

Returns: The smallest value.

Examples:

// Multiple arguments
{ "min": [5, 1, 3] }
// Result: 1

// A single argument that resolves to an array (data-driven)
{ "min": { "var": "prices" } }
// Data: { "prices": [29.99, 19.99, 39.99] }
// Result: 19.99

// Note: a literal nested array passed positionally, e.g. { "min": [[5, 1, 3]] }
// or { "min": [[]] }, is an invalid operand and throws Invalid Arguments.
// Pass scalars directly, or a value that resolves to an array.

Try it:

Notes:

• Operands must be numbers. min does not coerce strings (even numeric ones), booleans, or null; they throw Invalid Arguments
• An empty argument list, or a single value that resolves to an empty array, throws Invalid Arguments

abs

Get the absolute value.

Syntax:

{ "abs": value }
{ "abs": [a, b, ...] }

Arguments:

• value - Number to get absolute value of (a numeric string is coerced)
• a, b, … - Two or more numbers; the result is an array of per-element absolute values

Returns: Absolute (positive) value, or an array of them for the multi-argument form.

Examples:

{ "abs": -5 }
// Result: 5

{ "abs": 5 }
// Result: 5

{ "abs": -3.14 }
// Result: 3.14

{ "abs": 0 }
// Result: 0

// Distance between two points
{ "abs": { "-": [{ "var": "a" }, { "var": "b" }] } }
// Data: { "a": 3, "b": 10 }
// Result: 7

// Numeric strings are coerced
{ "abs": "-5" }
// Result: 5

// Multiple arguments: element-wise
{ "abs": [-1, 2] }
// Result: [1, 2]

Try it:

Notes (abs, ceil, floor):

• Numeric strings are coerced; null, booleans, non-numeric strings and the strings "NaN", "inf" and "infinity" throw Invalid Arguments. arithmetic_nan_handling does not apply
• Two or more arguments return an array of per-element results
• Unlike max/min, a single value that resolves to an array throws Invalid Arguments: { "abs": { "var": "a" } } with { "a": [-1] } is an error. Use map to apply these to a data-driven array
• ceil and floor return an integer when the result fits in i64, and a float otherwise ({ "ceil": 1e20 } is 1e20)

ceil

Round up to the nearest integer.

Syntax:

{ "ceil": value }
{ "ceil": [a, b, ...] }

Arguments:

• value - Number to round up (a numeric string is coerced)
• a, b, … - Two or more numbers; the result is an array of per-element results

Returns: Smallest integer greater than or equal to value, or an array of them for the multi-argument form. See the notes under abs for argument rules.

Examples:

{ "ceil": 4.1 }
// Result: 5

{ "ceil": 4.9 }
// Result: 5

{ "ceil": 4.0 }
// Result: 4

{ "ceil": -4.1 }
// Result: -4

// Round up to whole units
{ "ceil": { "/": [{ "var": "items" }, 10] } }
// Data: { "items": 25 }
// Result: 3 (need 3 boxes of 10)

// Multiple arguments: element-wise
{ "ceil": [1.2, 2] }
// Result: [2, 2]

Try it:

floor

Round down to the nearest integer.

Syntax:

{ "floor": value }
{ "floor": [a, b, ...] }

Arguments:

• value - Number to round down (a numeric string is coerced)
• a, b, … - Two or more numbers; the result is an array of per-element results

Returns: Largest integer less than or equal to value, or an array of them for the multi-argument form. See the notes under abs for argument rules.

Examples:

{ "floor": 4.9 }
// Result: 4

{ "floor": 4.1 }
// Result: 4

{ "floor": 4.0 }
// Result: 4

{ "floor": -4.1 }
// Result: -5

// Truncate decimal
{ "floor": { "var": "amount" } }
// Data: { "amount": 99.99 }
// Result: 99

// Multiple arguments: element-wise
{ "floor": [1.2, 2] }
// Result: [1, 2]

Try it:

Non-numeric operands

+, -, *, / and % read numeric strings ("5", "-3.14", "1e3"), booleans (true is 1, false is 0), null and "" (both 0) as numbers. EvaluationConfig::numeric_coercion turns the last three off (see Numeric Coercion). The strings "NaN", "inf" and "infinity", and numeric strings that overflow f64 ("1e400"), are not numbers.

Any other operand, such as "abc", an array or an object, raises a NaN error by default. EvaluationConfig::arithmetic_nan_handling changes that for + and *, and for the operands after the first in a - call with three or more operands:

/ and % raise a NaN error for a non-numeric operand under every setting, and so does -, except for the operands after the first in a call with three or more. See NaN Handling.

See Also

• Configuration (NanHandling, DivisionByZeroHandling, NumericCoercionConfig): customize arithmetic coercion and error behavior
• DateTime Operators: add, subtract, and scale datetimes and durations with +, -, *, and /
• Error Handling (try, throw): catch arithmetic NaN and division-by-zero errors
• Operators Overview: full operator table and feature flags

Control Flow Operators

Conditional branching and value selection operators.

Feature flags (Rust crate). if and ?: are baseline; ??, switch/match, and type require the ext-control feature. Every language binding enables all operator features. See the feature table.

Argument counts: if / ?: take one or more arguments, ?? any number, switch / match two or three (value, case table, default), and type one. With no arguments, if and ?? return null and type returns "null"; switch with fewer than two arguments returns null. Extra arguments to switch and type are never evaluated.

if

Conditional branching with if/then/else chains.

Syntax:

{ "if": [condition, then_value] }
{ "if": [condition, then_value, else_value] }
{ "if": [cond1, value1, cond2, value2, ..., else_value] }

Arguments:

• condition - Condition to evaluate
• then_value - Value if condition is truthy
• else_value - Value if condition is falsy (optional)
• Additional condition/value pairs for else-if chains

Returns: The value corresponding to the first truthy condition, or the else value.

Examples:

// Simple if/then
{ "if": [true, "yes"] }
// Result: "yes"

{ "if": [false, "yes"] }
// Result: null

// If/then/else
{ "if": [true, "yes", "no"] }
// Result: "yes"

{ "if": [false, "yes", "no"] }
// Result: "no"

// If/else-if/else chain
{ "if": [
    { ">=": [{ "var": "score" }, 90] }, "A",
    { ">=": [{ "var": "score" }, 80] }, "B",
    { ">=": [{ "var": "score" }, 70] }, "C",
    { ">=": [{ "var": "score" }, 60] }, "D",
    "F"
]}
// Data: { "score": 85 }
// Result: "B"

// Nested if
{ "if": [
    { "var": "premium" },
    { "if": [
        { ">": [{ "var": "amount" }, 100] },
        "free_shipping",
        "standard_shipping"
    ]},
    "no_shipping"
]}
// Data: { "premium": true, "amount": 150 }
// Result: "free_shipping"

Try it:

Notes:

• Only evaluates the matching branch (lazy evaluation)
• Empty condition list returns null
• Odd number of arguments uses last as else value
• if takes its arguments as an array only: { "if": true } raises Invalid Arguments

?: (Ternary)

Ternary conditional operator (shorthand if/then/else). ?: is an input alias of if: it compiles to the same operator, so it accepts every argument shape if does, including the two-argument form and else-if chains.

Syntax:

{ "?:": [condition, then_value, else_value] }
{ "?:": [condition, then_value] }
{ "?:": [cond1, value1, cond2, value2, ..., else_value] }

Arguments:

• condition - Condition to evaluate
• then_value - Value if condition is truthy
• else_value - Value if condition is falsy (optional; null when omitted)
• Additional condition/value pairs for else-if chains, exactly as with if

Returns: then_value if condition is truthy, else_value otherwise (the same rules as if).

Examples:

// Basic ternary
{ "?:": [true, "yes", "no"] }
// Result: "yes"

{ "?:": [false, "yes", "no"] }
// Result: "no"

// With comparison
{ "?:": [
    { ">": [{ "var": "age" }, 18] },
    "adult",
    "minor"
]}
// Data: { "age": 21 }
// Result: "adult"

// Nested ternary
{ "?:": [
    { "var": "vip" },
    0,
    { "?:": [
        { ">": [{ "var": "total" }, 50] },
        5,
        10
    ]}
]}
// Data: { "vip": false, "total": 75 }
// Result: 5 (shipping cost)

// Two-argument and chained forms work exactly as they do for if
{ "?:": [false, "yes"] }
// Result: null

{ "?:": [false, 1, true, 2, 3] }
// Result: 2

Try it:

Notes:

• { "?:": [c, a, b] } is exactly { "if": [c, a, b] }, and the argument rules in the if section apply unchanged
• Only evaluates the matching branch

?? (Null Coalesce)

Return the first non-null value.

Syntax:

{ "??": [a, b] }
{ "??": [a, b, c, ...] }

Arguments:

• a, b, … - Values to check (variadic)

Returns: The first non-null value, or null if all are null.

Examples:

// First is not null
{ "??": ["hello", "default"] }
// Result: "hello"

// First is null
{ "??": [null, "default"] }
// Result: "default"

// Multiple values
{ "??": [null, null, "found"] }
// Result: "found"

// All null
{ "??": [null, null] }
// Result: null

// With variables (default value pattern)
{ "??": [{ "var": "nickname" }, { "var": "name" }, "Anonymous"] }
// Data: { "name": "Alice" }
// Result: "Alice"

// Note: 0, "", and false are NOT null
{ "??": [0, "default"] }
// Result: 0

{ "??": ["", "default"] }
// Result: ""

{ "??": [false, "default"] }
// Result: false

Try it:

Notes:

• Only checks for null, not other falsy values
• Use or if you want to skip all falsy values
• Short-circuits: stops at first non-null value

switch / match

Match a value against a list of cases, returning the result of the first case whose key strictly equals the value, or a default. match is an alias of switch.

Syntax:

{ "switch": [value, [[case, result], ...]] }
{ "switch": [value, [[case, result], ...], default] }

Arguments:

• value - The discriminant, evaluated once
• [[case, result], ...] - Array of [case, result] pairs; the first case that strictly equals value selects its result
• default - Optional value used when no case matches (omitted: returns null)

Returns: The matched case’s result, the default, or null.

Examples:

{ "switch": [
    { "var": "color" },
    [["red", "stop"], ["green", "go"]],
    "unknown"
]}
// Data: { "color": "green" }
// Result: "go"

// Alias `match`
{ "match": [
    { "var": "status" },
    [[200, "OK"], [404, "Not Found"]],
    "Unknown"
]}
// Data: { "status": 404 }
// Result: "Not Found"

// Strict matching: the number 1 does not match the string "1"
{ "switch": [1, [["1", "str"], [1, "num"]], "none"] }
// Result: "num"

// No match and no default
{ "switch": [{ "var": "x" }, [[1, "a"]]] }
// Data: { "x": 2 }
// Result: null

Notes:

• Case comparison is strict (no type coercion): the number 1 does not match the string "1".
• switch evaluates the discriminant once and compares it against each case in order.
• switch evaluates only the matching case’s result (or the default).
• Case keys may be expressions: { "switch": [{ "var": "x" }, [[{ "var": "y" }, "dyn"]], "d"] } returns "dyn" when x equals y.
• Write the case table in the rule. A case table computed at evaluation time ({ "switch": [{ "var": "x" }, { "var": "cases" }, "d"] }) matches nothing, so the call returns the default.
• switch reads at most three arguments; a fourth is never evaluated.

type

Return the runtime type of a value as a string.

Syntax:

{ "type": value }

Arguments:

• value - Any value to inspect

Returns: One of "null", "boolean", "number", "string", "array", "object", "datetime", "duration", or (with the tensor feature) "tensor".

Examples:

{ "type": 42 }
// Result: "number"

{ "type": "hello" }
// Result: "string"

// A value that resolves to an array
{ "type": { "var": "items" } }
// Data: { "items": [1, 2, 3] }
// Result: "array"

{ "type": { "now": [] } }
// Result: "datetime"

// Strings are classified with the datetime and duration parsers
{ "type": "2024-01-15T10:30:00-05:00" }
// Result: "datetime"

{ "type": "2h30m" }
// Result: "duration"

{ "type": "password1" }
// Result: "string"

Notes:

• type reads exactly one argument. The engine parses a literal array such as { "type": [1, 2, 3] } as a multi-argument call, so type inspects the first element (here, "number"). Pass a single value that resolves to an array, such as { "type": { "var": "items" } }, or wrap the literal: { "type": [[1, 2, 3]] } is "array".
• With the datetime feature, type classifies a string the way the comparisons decide to compare it: a string that parses as an ISO 8601 datetime, with an offset or naive, is "datetime"; one that parses as a duration is "duration"; anything else is "string". The results of now, datetime and timestamp are such strings.
• A single-key { "datetime": "..." } or { "timestamp": "..." } object in data is "datetime" or "duration". An object with any other key beside it is "object".

Comparison: if vs ?: vs ?? vs or

Examples:

// Value is 0 (falsy but not null)
// Data: { "count": 0 }

{ "if": [{ "var": "count" }, { "var": "count" }, 10] }
// Result: 10 (0 is falsy)

{ "?:": [{ "var": "count" }, { "var": "count" }, 10] }
// Result: 10 (0 is falsy)

{ "??": [{ "var": "count" }, 10] }
// Result: 0 (0 is not null)

{ "or": [{ "var": "count" }, 10] }
// Result: 10 (0 is falsy)

Choose the operator based on whether you want to treat 0, "", and false as valid values.

See Also

• Logical Operators (!, !!, and, or): short-circuit boolean logic and truthiness rules
• Error Handling (try, throw): catch runtime errors and provide fallback expressions
• Variable Access (var, val, exists): read data fields with optional defaults
• Operators Overview: full operator table and feature flags

String Operators

String manipulation and searching operations.

Feature flags (Rust crate). cat, substr, and in are baseline. length, starts_with, ends_with, upper, lower, trim, and split require the ext-string feature. Every language binding enables all operator features, so this only affects the Rust crate. See the feature table.

Argument counts: cat takes any number of arguments; substr one to three; in, starts_with, ends_with and split two; length, upper, lower and trim one. With too few arguments, substr returns "", in returns false, and the others raise Invalid Arguments. Extra arguments are ignored, except by length, which raises Invalid Arguments.

substr, starts_with, ends_with, upper, lower, trim and split convert a non-string argument to its string form first: 12 becomes "12" and null becomes "".

cat

Concatenate strings together.

Syntax:

{ "cat": [a, b, ...] }

Arguments:

• a, b, … - Values to concatenate (variadic)

Returns: Concatenated string. Numbers and booleans add their text, null adds nothing, and an array argument adds each of its items.

Examples:

// Simple concatenation
{ "cat": ["Hello", " ", "World"] }
// Result: "Hello World"

// With variables
{ "cat": ["Hello, ", { "var": "name" }, "!"] }
// Data: { "name": "Alice" }
// Result: "Hello, Alice!"

// Non-strings are converted
{ "cat": ["Value: ", 42] }
// Result: "Value: 42"

{ "cat": ["Is active: ", true] }
// Result: "Is active: true"

// Building paths
{ "cat": ["/users/", { "var": "userId" }, "/profile"] }
// Data: { "userId": 123 }
// Result: "/users/123/profile"

Try it:

substr

Extract a substring.

Syntax:

{ "substr": [string, start] }
{ "substr": [string, start, length] }

Arguments:

• string - Source string
• start - Starting index (0-based, negative counts from end)
• length - Number of characters (optional, negative counts from end)

A start or length that is not an integer counts as absent: { "substr": ["abcdef", 1.5] } is "abcdef".

Returns: Extracted substring.

Examples:

// From start index
{ "substr": ["Hello World", 0, 5] }
// Result: "Hello"

// From middle
{ "substr": ["Hello World", 6] }
// Result: "World"

// Negative start (from end)
{ "substr": ["Hello World", -5] }
// Result: "World"

// Negative length (exclude from end)
{ "substr": ["Hello World", 0, -6] }
// Result: "Hello"

// Get file extension
{ "substr": ["document.pdf", -3] }
// Result: "pdf"

// With variables
{ "substr": [{ "var": "text" }, 0, 10] }
// Data: { "text": "This is a long string" }
// Result: "This is a "

Try it:

in

Check if a value is contained in a string or array.

Syntax:

{ "in": [needle, haystack] }

Arguments:

• needle - Value to search for
• haystack - String or array to search in

Returns: true if found, false otherwise.

Examples:

// String contains substring
{ "in": ["World", "Hello World"] }
// Result: true

{ "in": ["xyz", "Hello World"] }
// Result: false

// Array contains element
{ "in": [2, [1, 2, 3]] }
// Result: true

{ "in": [5, [1, 2, 3]] }
// Result: false

// Check membership
{ "in": [{ "var": "role" }, ["admin", "moderator"]] }
// Data: { "role": "admin" }
// Result: true

// Check substring
{ "in": ["@", { "var": "email" }] }
// Data: { "email": "user@example.com" }
// Result: true

Try it:

Notes:

• A string haystack requires a string needle: { "in": [2, "123"] } is false; the engine never stringifies numbers for substring search
• Array membership uses strict deep equality (the same predicate as distinct): { "in": ["2", [1, 2, 3]] } is false, while { "in": [1, [1.0, 2]] } is true and nested arrays/objects compare structurally
• Any other haystack (an object, null, a missing variable) yields false, as does a missing haystack argument

length

Get the length of a string or array.

Syntax:

{ "length": value }

Arguments:

• value - String or array

Returns: Length (number of characters or elements).

Examples:

// String length
{ "length": "Hello" }
// Result: 5

// Array length (pass a value that resolves to an array)
{ "length": { "var": "nums" } }
// Data: { "nums": [1, 2, 3, 4, 5] }
// Result: 5

// Empty string
{ "length": "" }
// Result: 0

// Empty array (data-driven)
{ "length": { "var": "empty" } }
// Data: { "empty": [] }
// Result: 0

// With variables
{ "length": { "var": "items" } }
// Data: { "items": ["a", "b", "c"] }
// Result: 3

// Check minimum length
{ ">=": [{ "length": { "var": "password" } }, 8] }
// Data: { "password": "secret123" }
// Result: true

Notes:

• length takes exactly one argument. The engine parses a literal array such as { "length": [1, 2, 3] } as a multi-argument call, which throws Invalid Arguments. Pass a single value that resolves to an array (for example { "length": { "var": "items" } }), or wrap the literal in one more array: { "length": [[1, 2, 3]] } is 3.
• length accepts only strings and arrays: null (including a missing var), numbers, booleans, and objects throw Invalid Arguments. Guard optional fields with ??, for example { "length": { "??": [{ "var": "items" }, []] } }, which is 0 when items is absent.
• String length counts Unicode characters, not bytes ({ "length": "héllo" } is 5).

Try it:

starts_with

Check if a string starts with a prefix.

Syntax:

{ "starts_with": [string, prefix] }

Arguments:

• string - String to check
• prefix - Prefix to look for

Returns: true if string starts with prefix, false otherwise.

Examples:

{ "starts_with": ["Hello World", "Hello"] }
// Result: true

{ "starts_with": ["Hello World", "World"] }
// Result: false

// Check URL scheme
{ "starts_with": [{ "var": "url" }, "https://"] }
// Data: { "url": "https://example.com" }
// Result: true

// Case sensitive
{ "starts_with": ["Hello", "hello"] }
// Result: false

Try it:

ends_with

Check if a string ends with a suffix.

Syntax:

{ "ends_with": [string, suffix] }

Arguments:

• string - String to check
• suffix - Suffix to look for

Returns: true if string ends with suffix, false otherwise.

Examples:

{ "ends_with": ["Hello World", "World"] }
// Result: true

{ "ends_with": ["Hello World", "Hello"] }
// Result: false

// Check file extension
{ "ends_with": [{ "var": "filename" }, ".pdf"] }
// Data: { "filename": "report.pdf" }
// Result: true

// Case sensitive
{ "ends_with": ["test.PDF", ".pdf"] }
// Result: false

Try it:

upper

Convert string to uppercase.

Syntax:

{ "upper": string }

Arguments:

• string - String to convert

Returns: Uppercase string.

Examples:

{ "upper": "hello" }
// Result: "HELLO"

{ "upper": "Hello World" }
// Result: "HELLO WORLD"

// With variable
{ "upper": { "var": "name" } }
// Data: { "name": "alice" }
// Result: "ALICE"

// Unicode case mapping can change the length
{ "upper": "straße" }
// Result: "STRASSE"

Try it:

lower

Convert string to lowercase.

Syntax:

{ "lower": string }

Arguments:

• string - String to convert

Returns: Lowercase string.

Examples:

{ "lower": "HELLO" }
// Result: "hello"

{ "lower": "Hello World" }
// Result: "hello world"

// Case-insensitive comparison
{ "==": [
    { "lower": { "var": "input" } },
    "yes"
]}
// Data: { "input": "YES" }
// Result: true

// Context-sensitive rules: a final Greek capital sigma becomes ς
{ "lower": "ΟΔΟΣ" }
// Result: "οδος"

Try it:

Notes:

• upper and lower apply Unicode’s full case mappings (Rust’s str::to_uppercase / str::to_lowercase), context-sensitive rules such as the Greek final sigma included

trim

Remove leading and trailing whitespace.

Syntax:

{ "trim": string }

Arguments:

• string - String to trim

Returns: String with whitespace removed from both ends.

Examples:

{ "trim": "  hello  " }
// Result: "hello"

{ "trim": "\n\ttext\n\t" }
// Result: "text"

// Clean user input
{ "trim": { "var": "userInput" } }
// Data: { "userInput": "  search query  " }
// Result: "search query"

Try it:

split

Split a string into an array.

Syntax:

{ "split": [string, delimiter] }

Arguments:

• string - String to split
• delimiter - Delimiter to split on

Returns: Array of substrings.

Examples:

// Split by space
{ "split": ["Hello World", " "] }
// Result: ["Hello", "World"]

// Split by comma
{ "split": ["a,b,c", ","] }
// Result: ["a", "b", "c"]

// Split by empty string (characters)
{ "split": ["abc", ""] }
// Result: ["a", "b", "c"]

// Parse CSV-like data
{ "split": [{ "var": "tags" }, ","] }
// Data: { "tags": "rust,json,logic" }
// Result: ["rust", "json", "logic"]

// Split an email address
{ "split": ["user@example.com", "@"] }
// Result: ["user", "example.com"]

Try it:

Notes:

• split reads exactly two arguments. There is no limit argument: { "split": ["a,b,c,d", ",", 2] } still returns all four parts, and a single argument is Invalid Arguments
• An empty input string gives [""]

See Also

• Array Operators (slice, merge, map, filter): slice and transform arrays produced by split
• Comparison Operators (==, ===): compare strings lexicographically or with type coercion
• Operators Overview: full operator table and feature flags

Array Operators

Operations for working with arrays, including iteration and transformation.

Feature flags (Rust crate). All array operators are baseline except sort, slice, group_by, and distinct, which require the ext-array feature. Every language binding enables all operator features. An engine built with EngineBuilder::with_families has those four only if it names Family::ExtArray. See the feature table.

The JSONLogic iterators (filter, map, reduce, all, some, none) reject extra arguments with an Invalid Arguments error; sort, group_by and distinct ignore them. Inside an iterator, {"var": ""} is the current element; Scope levels reach enclosing elements and the element’s index or key.

merge

Concatenate multiple arrays into one.

Syntax:

{ "merge": [array1, array2, ...] }

Arguments:

• array1, array2, … - Arrays to concatenate; merge wraps scalars and objects as single elements

Returns: A single array: the arguments concatenated one level deep. Nested arrays inside an argument stay as elements (no deep flatten), and merge drops null arguments and null elements.

Examples:

// Merge two arrays
{ "merge": [[1, 2], [3, 4]] }
// Result: [1, 2, 3, 4]

// Merge multiple
{ "merge": [[1], [2], [3]] }
// Result: [1, 2, 3]

// Non-arrays are wrapped
{ "merge": [[1, 2], 3, [4, 5]] }
// Result: [1, 2, 3, 4, 5]

// With variables
{ "merge": [{ "var": "arr1" }, { "var": "arr2" }] }
// Data: { "arr1": [1, 2], "arr2": [3, 4] }
// Result: [1, 2, 3, 4]

// Only one level is flattened
{ "merge": [[1, [2, [3]]], [4]] }
// Result: [1, [2, [3]], 4]

// Nulls are dropped
{ "merge": [[1, null, 2], null] }
// Result: [1, 2]

Try it:

Notes:

• Flattens exactly one level; use nested merge calls for deeper structures
• null arguments and null elements are skipped; a scalar argument is wrapped ({ "merge": 1 } is [1])

filter

Filter array elements based on a condition.

Syntax:

{ "filter": [array, condition] }

Arguments:

• array - Array to filter (an object is also accepted, see Notes)
• condition - Condition applied to each element (use {"var": ""} for current element)

Returns: Array of elements where condition is truthy. For an object input, an object of the key/value pairs whose value passes.

Examples:

// Filter numbers greater than 2
{ "filter": [
    [1, 2, 3, 4, 5],
    { ">": [{ "var": "" }, 2] }
]}
// Result: [3, 4, 5]

// Filter even numbers
{ "filter": [
    [1, 2, 3, 4, 5, 6],
    { "==": [{ "%": [{ "var": "" }, 2] }, 0] }
]}
// Result: [2, 4, 6]

// Filter objects by property
{ "filter": [
    { "var": "users" },
    { "==": [{ "var": "active" }, true] }
]}
// Data: {
//   "users": [
//     { "name": "Alice", "active": true },
//     { "name": "Bob", "active": false },
//     { "name": "Carol", "active": true }
//   ]
// }
// Result: [{ "name": "Alice", "active": true }, { "name": "Carol", "active": true }]

// Filter with multiple conditions
{ "filter": [
    { "var": "products" },
    { "and": [
        { ">": [{ "var": "price" }, 10] },
        { "var": "inStock" }
    ]}
]}

Try it:

Notes:

• filter does not modify the original array
• A field an element lacks reads as null, so { "filter": [{ "var": "rows" }, { "===": [{ "var": "v" }, null] }] } keeps the elements without v as well as those whose v is null
• filter filters an object input by its values and returns an object of the kept pairs: { "filter": [{ "var": "x" }, { ">": [{ "var": "" }, 3] }] } with { "x": { "a": 1, "b": 5 } } is { "b": 5 }
• A null or missing input yields []; a scalar input is an Invalid Arguments error

map

Transform each element of an array.

Syntax:

{ "map": [array, transformation] }

Arguments:

• array - Array to transform
• transformation - Operation applied to each element

Returns: Array of transformed elements.

Examples:

// Double each number
{ "map": [
    [1, 2, 3],
    { "*": [{ "var": "" }, 2] }
]}
// Result: [2, 4, 6]

// Extract property from objects
{ "map": [
    { "var": "users" },
    { "var": "name" }
]}
// Data: {
//   "users": [
//     { "name": "Alice", "age": 30 },
//     { "name": "Bob", "age": 25 }
//   ]
// }
// Result: ["Alice", "Bob"]

// Create new objects
{ "map": [
    { "var": "items" },
    { "cat": ["Item: ", { "var": "name" }] }
]}
// Data: { "items": [{ "name": "A" }, { "name": "B" }] }
// Result: ["Item: A", "Item: B"]

// Square numbers
{ "map": [
    [1, 2, 3, 4],
    { "*": [{ "var": "" }, { "var": "" }] }
]}
// Result: [1, 4, 9, 16]

Try it:

Notes:

• An object input maps over its values and returns an array ({ "a": 1, "b": 5 } doubled is [2, 10])
• A null or missing input yields []; map treats a scalar input as a one-element array ({ "map": [5, { "*": [{ "var": "" }, 2] }] } is [10])

reduce

Reduce an array to a single value.

Syntax:

{ "reduce": [array, reducer, initial] }
{ "reduce": [array, reducer] }

Arguments:

• array - Array to reduce
• reducer - Operation combining accumulator and current element
• initial - Initial value for accumulator (optional). When omitted, the first element seeds the accumulator and reduction starts from the second; an empty array without initial yields null

Returns: Final accumulated value.

Context Variables:

• {"var": "current"} - Current element
• {"var": "accumulator"} - Current accumulated value
• Dotted paths read inside them: {"var": "current.price"}, {"var": "accumulator.total"}

Examples:

// Sum all numbers
{ "reduce": [
    [1, 2, 3, 4, 5],
    { "+": [{ "var": "accumulator" }, { "var": "current" }] },
    0
]}
// Result: 15

// Product of all numbers
{ "reduce": [
    [1, 2, 3, 4],
    { "*": [{ "var": "accumulator" }, { "var": "current" }] },
    1
]}
// Result: 24

// Concatenate strings
{ "reduce": [
    ["a", "b", "c"],
    { "cat": [{ "var": "accumulator" }, { "var": "current" }] },
    ""
]}
// Result: "abc"

// Find maximum
{ "reduce": [
    [3, 1, 4, 1, 5, 9],
    { "if": [
        { ">": [{ "var": "current" }, { "var": "accumulator" }] },
        { "var": "current" },
        { "var": "accumulator" }
    ]},
    0
]}
// Result: 9

// Count elements matching condition
{ "reduce": [
    [1, 2, 3, 4, 5, 6],
    { "+": [
        { "var": "accumulator" },
        { "if": [{ ">": [{ "var": "current" }, 3] }, 1, 0] }
    ]},
    0
]}
// Result: 3 (count of numbers > 3)

// Without initial: the first element seeds the accumulator
{ "reduce": [
    [1, 2, 3],
    { "+": [{ "var": "accumulator" }, { "var": "current" }] }
]}
// Result: 6

// Empty array without initial
{ "reduce": [
    [],
    { "+": [{ "var": "accumulator" }, { "var": "current" }] }
]}
// Result: null

Try it:

Notes:

• An object input reduces over its values
• A null, missing, or scalar input returns initial unchanged (null when initial is omitted)
• The accumulator may nest at most 1,024 levels of arrays and objects. A reducer that wraps the accumulator once per element ([{ "var": "accumulator" }]) fails with an Invalid Arguments error once it passes that depth

all

Check if all elements satisfy a condition.

Syntax:

{ "all": [array, condition] }

Arguments:

• array - Array to check
• condition - Condition applied to each element

Returns: true if all elements satisfy condition, false otherwise.

Examples:

// All positive
{ "all": [
    [1, 2, 3],
    { ">": [{ "var": "" }, 0] }
]}
// Result: true

// All greater than 5
{ "all": [
    [1, 2, 3],
    { ">": [{ "var": "" }, 5] }
]}
// Result: false

// All users active
{ "all": [
    { "var": "users" },
    { "var": "active" }
]}
// Data: { "users": [{ "active": true }, { "active": true }] }
// Result: true

// Empty array returns false (in this engine, all-of-empty is false)
{ "all": [[], { ">": [{ "var": "" }, 0] }] }
// Result: false

Try it:

Notes (all, some, none):

• Each stops at the first element that decides the result and does not evaluate the condition for the rest
• An object input checks the object’s values
• A null, missing, or scalar input counts as an empty collection: all is false, some is false, none is true

some

Check if any element satisfies a condition.

Syntax:

{ "some": [array, condition] }

Arguments:

• array - Array to check
• condition - Condition applied to each element

Returns: true if at least one element satisfies condition, false otherwise.

Examples:

// Any negative
{ "some": [
    [1, -2, 3],
    { "<": [{ "var": "" }, 0] }
]}
// Result: true

// Any greater than 10
{ "some": [
    [1, 2, 3],
    { ">": [{ "var": "" }, 10] }
]}
// Result: false

// Any admin user
{ "some": [
    { "var": "users" },
    { "==": [{ "var": "role" }, "admin"] }
]}
// Data: {
//   "users": [
//     { "role": "user" },
//     { "role": "admin" }
//   ]
// }
// Result: true

// Empty array returns false
{ "some": [[], { ">": [{ "var": "" }, 0] }] }
// Result: false

Try it:

none

Check if no elements satisfy a condition.

Syntax:

{ "none": [array, condition] }

Arguments:

• array - Array to check
• condition - Condition applied to each element

Returns: true if no elements satisfy condition, false otherwise.

Examples:

// None negative
{ "none": [
    [1, 2, 3],
    { "<": [{ "var": "" }, 0] }
]}
// Result: true

// None greater than 0
{ "none": [
    [1, 2, 3],
    { ">": [{ "var": "" }, 0] }
]}
// Result: false

// No banned users
{ "none": [
    { "var": "users" },
    { "var": "banned" }
]}
// Data: { "users": [{ "banned": false }, { "banned": false }] }
// Result: true

// Empty array returns true
{ "none": [[], { ">": [{ "var": "" }, 0] }] }
// Result: true

Try it:

sort

Sort an array.

Syntax:

{ "sort": [array] }
{ "sort": [array, ascending] }
{ "sort": [array, ascending, key_extractor] }

Arguments:

• array - Array to sort (a value that resolves to an array)
• ascending - Optional direction boolean: true (or omitted) sorts ascending, false sorts descending
• key_extractor - Optional per-element expression that produces the sort key for each element

Returns: Sorted array.

Examples:

// Sort numbers (ascending by default)
{ "sort": [[3, 1, 4, 1, 5, 9]] }
// Result: [1, 1, 3, 4, 5, 9]

// Sort strings
{ "sort": [["banana", "apple", "cherry"]] }
// Result: ["apple", "banana", "cherry"]

// Sort descending
{ "sort": [{ "var": "nums" }, false] }
// Data: { "nums": [3, 1, 4, 1, 5, 9] }
// Result: [9, 5, 4, 3, 1, 1]

// Sort objects ascending by a key extractor
{ "sort": [
    { "var": "items" },
    true,
    { "var": "price" }
]}
// Data: {
//   "items": [
//     { "name": "B", "price": 20 },
//     { "name": "A", "price": 10 }
//   ]
// }
// Result: [{ "name": "A", "price": 10 }, { "name": "B", "price": 20 }]

Try it:

Notes:

• The second argument is a direction boolean: true (or omitted) sorts ascending, false descending. A non-boolean direction falls back to ascending.
• The optional third argument is a per-element key extractor, evaluated with each element as its context. sort has no a/b comparator form.
• Numbers sort by exact value, so integers above 2^53 keep their order. Values of different types sort by type: null, booleans, numbers, strings, arrays, then objects. Two arrays, or two objects, tie.
• The sort is stable: elements that tie keep their input order. A key field an element lacks reads as null, so that element ties with one whose field is null.
• A null or missing input yields null (a literal null argument is Invalid Arguments). This differs from group_by and distinct, which yield [] for null input. An object or scalar input is Invalid Arguments.

slice

Extract a portion of an array or string.

Syntax:

{ "slice": [collection, start] }
{ "slice": [collection, start, end] }
{ "slice": [collection, start, end, step] }

Arguments:

• collection - Source array, or a string (sliced by character)
• start - Starting index (negative counts from end); null means the default (the first element)
• end - Ending index, exclusive (optional, negative counts from end); null means the default (the end of the collection)
• step - Optional stride (default 1); a negative step walks backwards, so [null, null, -1] reverses

Returns: Array slice, or a string slice for string input.

Examples:

// From index 2 to end
{ "slice": [[1, 2, 3, 4, 5], 2] }
// Result: [3, 4, 5]

// From index 1 to 3
{ "slice": [[1, 2, 3, 4, 5], 1, 3] }
// Result: [2, 3]

// Last 2 elements
{ "slice": [[1, 2, 3, 4, 5], -2] }
// Result: [4, 5]

// First 3 elements
{ "slice": [[1, 2, 3, 4, 5], 0, 3] }
// Result: [1, 2, 3]

// Pagination
{ "slice": [
    { "var": "items" },
    { "*": [{ "var": "page" }, 10] },
    { "+": [{ "*": [{ "var": "page" }, 10] }, 10] }
]}
// Data: { "items": [...], "page": 0 }
// Result: first 10 items

// Step: every second element
{ "slice": [[1, 2, 3, 4, 5], 0, 5, 2] }
// Result: [1, 3, 5]

// Negative step reverses
{ "slice": [[1, 2, 3, 4, 5], null, null, -1] }
// Result: [5, 4, 3, 2, 1]

// Strings are sliced by character
{ "slice": ["hello", 1, 3] }
// Result: "el"

{ "slice": ["hello", null, null, -1] }
// Result: "olleh"

Try it:

Notes:

• A null or missing collection yields null, without evaluating the bounds
• start, end and step must be integers or null. A whole float (2.0) counts as an integer; a fractional bound (1.5, written or computed), a string ("1") or a boolean is a NaN error
• step of 0 is an Invalid Arguments error, as is a collection that is neither an array nor a string

group_by

Collapse an array into groups on a computed key.

Syntax:

{ "group_by": [array, key_expression] }

Arguments:

• array - Array to group (a value that resolves to an array)
• key_expression - Per-element expression that produces each element’s group key (evaluated with the element as its context, like sort’s key extractor)

Returns: An array of {"key": ..., "items": [...]} rows, which map, filter and sort take as input. Groups appear in order of first key occurrence, so the output is deterministic for a given input.

Examples:

// Group tasks by status
{ "group_by": [{ "var": "tasks" }, { "var": "status" }] }
// Data: { "tasks": [
//   { "id": 1, "status": "open" },
//   { "id": 2, "status": "done" },
//   { "id": 3, "status": "open" }
// ]}
// Result: [
//   { "key": "open", "items": [{ "id": 1, "status": "open" }, { "id": 3, "status": "open" }] },
//   { "key": "done", "items": [{ "id": 2, "status": "done" }] }
// ]

// Group meetings by calendar date in the user's timezone
{ "group_by": [
    { "var": "meetings" },
    { "format_date": [{ "var": "start_time" }, "dd MMM yyyy", "Asia/Kolkata"] }
]}
// Result: [ { "key": "17 Aug 2026", "items": [ ... ] }, ... ]

// Group numbers by a computed key
{ "group_by": [[1, 2, 3, 4, 5], { "%": [{ "var": "" }, 2] }] }
// Result: [
//   { "key": 1, "items": [1, 3, 5] },
//   { "key": 0, "items": [2, 4] }
// ]

Try it:

Notes:

• group_by keeps keys as their evaluated values and does not stringify them: numbers, booleans, null, and objects group by deep equality.
• Elements whose key expression misses (resolves to null) group together under a null key.
• null or empty input yields []. Non-array input (scalar or object) is an error.

distinct

Drop duplicate elements, by value or by a computed key.

Syntax:

{ "distinct": [array] }
{ "distinct": [array, key_expression] }

Arguments:

• array - Array to deduplicate (a value that resolves to an array)
• key_expression - Optional per-element expression; when present, distinct deduplicates by the computed key instead of by value

Returns: Array with duplicates removed. The first occurrence wins, so output preserves input order.

Examples:

// Dedup by value
{ "distinct": [[3, 1, 3, 2, 1]] }
// Result: [3, 1, 2]

// Strict equality: 1 and "1" stay distinct
{ "distinct": [[1, "1", 1]] }
// Result: [1, "1"]

// Dedup objects structurally
{ "distinct": [{ "var": "items" }] }
// Data: { "items": [{ "a": 1 }, { "a": 2 }, { "a": 1 }] }
// Result: [{ "a": 1 }, { "a": 2 }]

// Dedup by key: one row per id, first revision wins
{ "distinct": [{ "var": "rows" }, { "var": "id" }] }
// Data: { "rows": [
//   { "id": 1, "rev": "a" },
//   { "id": 2, "rev": "b" },
//   { "id": 1, "rev": "c" }
// ]}
// Result: [{ "id": 1, "rev": "a" }, { "id": 2, "rev": "b" }]

Try it:

Notes:

• Equality is strict deep equality (the same predicate in uses): mixed types never merge, arrays and objects compare structurally. An object counts as a datetime only in the single-key form { "datetime": "..." }, so records that share a datetime field but differ elsewhere stay distinct.
• null or empty input yields []. Non-array input is an error.

See Also

• Variable Access: Scope Levels: access enclosing elements and iteration index / key inside map, filter, and reduce
• Object Operators (keys, values, entries): turn objects into arrays for iteration
• String Operators (in, length, split): check membership with in or measure array length with length
• Operators Overview: full operator table and feature flags

Object Operators

Operations for taking objects apart: enumerate keys, values, or key/value rows. These are the read-side complement of templating’s computed-key object construction; entries in particular turns any object into rows that the array vocabulary (map, filter, group_by, …) can iterate.

Feature flags (Rust crate). All object operators require the ext-object feature. Every language binding enables all operator features. An engine built with EngineBuilder::with_families has them only if it names Family::ExtObject. See the feature table.

keys

List an object’s keys.

Syntax:

{ "keys": [object] }

Arguments:

• object - A value that resolves to an object

Returns: Array of the object’s key strings, in stored order.

Examples:

{ "keys": [{ "var": "scores" }] }
// Data: { "scores": { "alice": 10, "bob": 7 } }
// Result: ["alice", "bob"]

Try it:

values

List an object’s values.

Syntax:

{ "values": [object] }

Arguments:

• object - A value that resolves to an object

Returns: Array of the object’s values, in stored order.

Examples:

{ "values": [{ "var": "scores" }] }
// Data: { "scores": { "alice": 10, "bob": 7 } }
// Result: [10, 7]

// Sum an object's values
{ "reduce": [
    { "values": [{ "var": "scores" }] },
    { "+": [{ "var": "accumulator" }, { "var": "current" }] },
    0
]}
// Result: 17

Try it:

entries

Turn an object into an array of {key, value} rows.

Syntax:

{ "entries": [object] }

Arguments:

• object - A value that resolves to an object

Returns: Array of {"key": ..., "value": ...} objects, in stored order.

Examples:

{ "entries": [{ "var": "scores" }] }
// Data: { "scores": { "alice": 10, "bob": 7 } }
// Result: [
//   { "key": "alice", "value": 10 },
//   { "key": "bob", "value": 7 }
// ]

// Iterate an object with the array vocabulary
{ "map": [
    { "entries": [{ "var": "scores" }] },
    { "cat": [{ "var": "key" }, ": ", { "var": "value" }] }
]}
// Result: ["alice: 10", "bob: 7"]

Try it:

Notes (all three operators):

• null input, including an absent field, yields [].
• Any other non-object input (array, string, number, boolean) is an Invalid Arguments error.
• Keys come out in stored order, duplicates included, exactly as the object carries them. The order depends on how the data entered: JSON text parsed by the engine (the ParsedData and string entry points, and the Node, WASM, and C-based bindings) keeps source-text order and duplicate keys, while data passed as a serde_json::Value or as a Python dict is key-sorted and duplicate-free (so { "zed": 10, "alpha": 7 } comes out as ["alpha", "zed"]). Do not rely on source-text order across input routes.

See Also

• Array Operators — iterate over entries rows with map, filter, reduce, and group_by
• Variable Access — read specific object fields with var, val, and exists
• Structured Objects (Templating) — construct new JSON objects dynamically
• Operators Overview — full operator catalog and feature-flag table

DateTime Operators

Operations for working with dates, times, and durations.

Feature flag (Rust crate). All datetime operators require the datetime feature (which pulls in chrono and chrono-tz). Every language binding enables it. See the feature table.

Argument counts: datetime and timestamp take one argument, parse_date and format_date two or three, date_diff three, and now none. A call with too few arguments raises InvalidArguments naming what is missing (for example "date_diff requires two dates and a unit"). The operators ignore arguments past the last one they read.

Datetime and duration values

The engine treats these values as datetimes and durations wherever an operator looks for one (comparisons, + / -, format_date, date_diff, type):

• A string that parses as an ISO 8601 / RFC 3339 datetime, such as "2024-01-15T10:30:00Z", "2024-01-15T10:30:00-05:00" or the naive "2024-01-15T10:30:00" (read as UTC), whether it is written in the rule, read from data or returned by another operator.
• A string that parses as a duration, such as "1d:2h:3m:4s", "2h30m" or "36h".
• The boundary forms {"datetime": "..."} and {"timestamp": "..."} in data. (In a rule, the same object is a call to the operator of that name.) Only an object with that single key counts: a record such as {"datetime": "2024-01-01T00:00:00Z", "user": "alice"} is ordinary data, so ==, ===, in and distinct compare every field and type reports "object".

The operators on this page and datetime arithmetic return datetimes as ISO 8601 strings and durations as "Xd:Xh:Xm:Xs" strings, so a result feeds straight into the next operator.

now

Get the current UTC datetime.

Syntax:

{ "now": [] }

Arguments: None

Returns: The current UTC time as an ISO 8601 datetime string.

Examples:

{ "now": [] }
// Result: "2024-01-15T14:30:00Z" (current time)

// Check if date is in the future
{ ">": [{ "var": "expiresAt" }, { "now": [] }] }
// Data: { "expiresAt": "2025-12-31T00:00:00Z" }
// Result: true or false depending on current time

// Check if event is happening now
{ "and": [
    { "<=": [{ "var": "startTime" }, { "now": [] }] },
    { ">=": [{ "var": "endTime" }, { "now": [] }] }
]}

Try it:

Notes:

• { "type": { "now": [] } } is "datetime"
• The result is in UTC (Z)
• The engine reads the clock at evaluation time and never constant-folds now, so a compiled rule sees a fresh time on every evaluation

datetime

Parse or validate a datetime value.

Syntax:

{ "datetime": value }

Arguments:

• value - An RFC 3339 datetime string (2024-01-01T00:00:00Z, or with a +HH:MM/-HH:MM offset; fractional seconds and a space instead of T are accepted), or a naive YYYY-MM-DDTHH:MM:SS string, which the engine reads as UTC. Date-only strings (2024-01-01) and colon-less offsets (-0500, +05) fail with Invalid datetime format; use parse_date for those and for custom formats

Returns: The argument unchanged once it parses, so the offset and spelling you passed are kept ("2024-01-01 00:00:00Z" comes back with its space). Any other value raises Invalid datetime format. { "type": { "datetime": "2024-01-01T00:00:00Z" } } is "datetime".

Examples:

// Parse ISO string
{ "datetime": "2024-01-01T00:00:00Z" }
// Result: "2024-01-01T00:00:00Z"

// With timezone offset
{ "datetime": "2024-01-01T10:00:00+05:30" }
// Result: "2024-01-01T10:00:00+05:30"

// Compare datetimes
{ ">": [
    { "datetime": "2024-06-15T00:00:00Z" },
    { "datetime": "2024-01-01T00:00:00Z" }
]}
// Result: true

// Add duration to datetime
{ "+": [
    { "datetime": "2024-01-01T00:00:00Z" },
    { "timestamp": "7d" }
]}
// Result: "2024-01-08T00:00:00Z"

Try it:

timestamp

Create or parse a duration value. Durations represent time periods (not points in time).

Syntax:

{ "timestamp": duration_string }

Arguments:

• duration_string - Duration in format like “1d:2h:3m:4s”, partial like “1d”, “2h”, “30m”, “45s”, or compact like “1d2h3m4s”

Returns: The duration as a normalized "Xd:Xh:Xm:Xs" string.

Duration Format:

• d - Days
• h - Hours
• m - Minutes
• s - Seconds

Examples:

// Full duration format
{ "timestamp": "1d:2h:3m:4s" }
// Result: "1d:2h:3m:4s"

// Days only
{ "timestamp": "2d" }
// Result: "2d:0h:0m:0s"

// Hours only
{ "timestamp": "5h" }
// Result: "0d:5h:0m:0s"

// Minutes only
{ "timestamp": "30m" }
// Result: "0d:0h:30m:0s"

// Compare durations
{ ">": [{ "timestamp": "2d" }, { "timestamp": "36h" }] }
// Result: true (2 days > 36 hours)

// Duration equality
{ "==": [{ "timestamp": "1d" }, { "timestamp": "24h" }] }
// Result: true

// Compact form
{ "timestamp": "1d2h3m4s" }
// Result: "1d:2h:3m:4s"

// Units overflow into the next larger unit
{ "timestamp": "36h" }
// Result: "1d:12h:0m:0s"

Notes:

• { "type": { "timestamp": "1d" } } is "duration"
• Units overflow into the next larger unit ("1d:25h" becomes "2d:1h:0m:0s")
• Negative ("-1d"), fractional ("1.5h"), week ("1w"), and numeric (3600) inputs fail with Invalid duration format

Try it:

Duration Arithmetic

+ and - accept datetimes and durations, * scales a duration by a number in either order, and / divides a duration by a number:

// Multiply duration
{ "*": [{ "timestamp": "1d" }, 2] }
// Result: "2d:0h:0m:0s"

// Divide duration
{ "/": [{ "timestamp": "2d" }, 2] }
// Result: "1d:0h:0m:0s"

// Add durations
{ "+": [{ "timestamp": "1d" }, { "timestamp": "12h" }] }
// Result: "1d:12h:0m:0s"

// Subtract durations
{ "-": [{ "timestamp": "2d" }, { "timestamp": "12h" }] }
// Result: "1d:12h:0m:0s"

// Add duration to datetime
{ "+": [
    { "datetime": "2024-01-01T00:00:00Z" },
    { "timestamp": "7d" }
]}
// Result: "2024-01-08T00:00:00Z"

// Subtract duration from datetime
{ "-": [
    { "datetime": "2024-01-15T00:00:00Z" },
    { "timestamp": "7d" }
]}
// Result: "2024-01-08T00:00:00Z"

// Difference between two datetimes (returns duration)
{ "-": [
    { "datetime": "2024-01-08T00:00:00Z" },
    { "datetime": "2024-01-01T00:00:00Z" }
]}
// Result: "7d:0h:0m:0s"

// The result of datetime +/- duration is a UTC instant: the parsed offset is not carried through
{ "+": [
    { "datetime": "2024-01-01T10:00:00+05:30" },
    { "timestamp": "1d" }
]}
// Result: "2024-01-02T04:30:00Z"

// Any number of operands, durations on either side of the datetime
{ "+": ["1d", { "var": "d" }, "12h"] }
// Data: { "d": "2024-01-01T00:00:00Z" }
// Result: "2024-01-02T12:00:00Z"

{ "-": [{ "var": "d" }, "1d", "1d"] }
// Data: { "d": "2024-01-08T00:00:00Z" }
// Result: "2024-01-06T00:00:00Z"

+ and - fold left to right. Datetime plus duration (in either order) is a datetime, datetime minus datetime is a duration, and two durations add or subtract to a duration. A step with no meaning is a NaN error under the default configuration: two datetimes added, a duration minus a datetime, or a plain number among datetime operands.

Arithmetic on a datetime that carries an offset drops that offset: the result renders as ...Z, and format_date with the bare "z" format reports +0000 for it. To render such a result in a local zone, pass the zone argument to format_date (for example "Asia/Kolkata", which gives "10:00" for the offset example above with format "HH:mm").

parse_date

Parse a date string with a custom format into a datetime value.

Syntax:

{ "parse_date": [string, format] }
{ "parse_date": [string, format, timezone] }

Arguments:

• string - Date string to parse
• format - Format string using simplified tokens
• timezone - Optional IANA zone name (e.g. "Asia/Kolkata"). Without it, the engine reads naive input as UTC; with it, the engine reads the input as wall-clock time in that zone and resolves it to the corresponding UTC instant.

Returns: The parsed instant as an ISO 8601 datetime string in UTC. Input that does not match the format raises Failed to parse date.

Format Tokens:

Raw chrono % specifiers also pass through unchanged.

Examples:

// Parse US date format
{ "parse_date": ["12/25/2024", "MM/dd/yyyy"] }
// Result: "2024-12-25T00:00:00Z"

// Parse European format
{ "parse_date": ["25-12-2024", "dd-MM-yyyy"] }
// Result: "2024-12-25T00:00:00Z"

// Parse date only
{ "parse_date": ["2024-01-15", "yyyy-MM-dd"] }
// Result: "2024-01-15T00:00:00Z"

// Read a naive local time as New York wall clock (EDT in June)
{ "parse_date": ["2024-06-15 12:00:00", "yyyy-MM-dd HH:mm:ss", "America/New_York"] }
// Result: "2024-06-15T16:00:00Z"

// With variable
{ "parse_date": [{ "var": "dateStr" }, "yyyy-MM-dd"] }
// Data: { "dateStr": "2024-06-15" }
// Result: "2024-06-15T00:00:00Z"

Timezone notes:

• Zone offsets, DST included, come from the IANA table compiled into the crate (chrono-tz); the engine reads no tzdata files at runtime.
• An ambiguous local time (clocks rolled back, the wall-clock occurs twice) resolves to the earlier instant; a nonexistent one (spring-forward gap) raises Nonexistent local time for timezone.
• An unknown zone name written as a literal in the rule does not stop Engine::compile: the call raises Invalid Arguments (naming the operator, not the zone) when the rule is evaluated, and Engine::check / Engine::compile_checked report the zone before the rule runs. A zone computed at evaluation time, from data or from another operator such as cat, fails with Unknown timezone: <name>.

Try it:

format_date

Format a datetime as a string with a custom format.

Syntax:

{ "format_date": [datetime, format] }
{ "format_date": [datetime, format, timezone] }

Arguments:

• datetime - Datetime value to format
• format - Format string using simplified tokens (same as parse_date)
• timezone - Optional IANA zone name (e.g. "Asia/Kolkata"). When present, format_date renders the instant as wall-clock time in that zone (DST-correct via the IANA table) instead of UTC.

Returns: Formatted date string. A first argument that is not a datetime raises Failed to format date. A raw % specifier that chrono does not know ("%Q") or a trailing lone % raises Invalid date format, whether the format is written in the rule or read from data.

Special Format:

• z - Returns the timezone offset (e.g., “+0500”). Without a zone argument this is the source offset the datetime was parsed with; with a zone argument it is the target zone’s offset at that instant.
• z is honoured only when it is the entire format string. Inside a longer format it is emitted literally: "yyyy-MM-dd HH:mm z" on 2024-01-01T10:00:00+05:30 gives "2024-01-01 04:30 z".
• Without a zone argument every other token renders the UTC instant, so "HH:mm" on that same value gives "04:30" and the raw chrono %z gives +0000; the source offset is reachable only through the bare "z" format. To get wall-clock time plus offset in one string, pass the zone argument and use %z or %Z: "HH:mm %z" with "Asia/Kolkata" gives "10:00 +0530", and "HH:mm %Z" gives "10:00 IST".

Examples:

// Format as date only
{ "format_date": [{ "datetime": "2024-01-15T14:30:00Z" }, "yyyy-MM-dd"] }
// Result: "2024-01-15"

// Format as US date
{ "format_date": [{ "datetime": "2024-12-25T00:00:00Z" }, "MM/dd/yyyy"] }
// Result: "12/25/2024"

// Get timezone offset (the format must be exactly "z")
{ "format_date": [{ "datetime": "2024-01-01T10:00:00+05:00" }, "z"] }
// Result: "+0500"

// Without a zone argument the other tokens render the UTC instant
{ "format_date": [{ "datetime": "2024-01-01T10:00:00+05:30" }, "HH:mm"] }
// Result: "04:30"

// Wall-clock time plus offset in one string needs the zone argument
{ "format_date": [{ "datetime": "2024-01-01T10:00:00+05:30" }, "HH:mm %z", "Asia/Kolkata"] }
// Result: "10:00 +0530"

// Render an instant as a calendar date in a zone
{ "format_date": [{ "datetime": "2026-08-17T18:30:00Z" }, "dd MMM yyyy", "Asia/Kolkata"] }
// Result: "18 Aug 2026"

// Zone offset at that instant (DST-aware)
{ "format_date": [{ "datetime": "2024-07-15T12:00:00Z" }, "z", "America/New_York"] }
// Result: "-0400"

// Format current time
{ "format_date": [{ "now": [] }, "yyyy-MM-dd"] }
// Result: "2024-01-15" (current date)

// With variable
{ "format_date": [{ "var": "date" }, "dd/MM/yyyy"] }
// Data: { "date": "2024-12-25T00:00:00Z" }
// Result: "25/12/2024"

// An unknown chrono specifier is an error (catchable with try)
{ "format_date": [{ "datetime": "2024-01-01T00:00:00Z" }, "%Q"] }
// Result: error (Invalid date format)

Try it:

date_diff

Calculate the difference between two dates in a specified unit.

Syntax:

{ "date_diff": [date1, date2, unit] }

Arguments:

• date1 - First datetime
• date2 - Second datetime
• unit - Unit of measurement: "days", "hours", "minutes", "seconds", or "milliseconds" (lowercase). Any other value is an Invalid Arguments error: date_diff: unknown unit "weeks" (expected days, hours, minutes, seconds, or milliseconds)

Returns: Difference (date1 - date2) as an integer in the specified unit, truncated toward zero; negative when date1 is earlier than date2.

Examples:

// Days between dates
{ "date_diff": [
    { "datetime": "2024-12-31T00:00:00Z" },
    { "datetime": "2024-01-01T00:00:00Z" },
    "days"
]}
// Result: 365

// Hours difference
{ "date_diff": [
    { "datetime": "2024-01-01T12:00:00Z" },
    { "datetime": "2024-01-01T00:00:00Z" },
    "hours"
]}
// Result: 12

// Milliseconds
{ "date_diff": [
    { "datetime": "2024-01-01T00:00:01Z" },
    { "datetime": "2024-01-01T00:00:00Z" },
    "milliseconds"
]}
// Result: 1000

// Negative when the first date is earlier
{ "date_diff": [
    { "datetime": "2024-01-01T00:00:00Z" },
    { "datetime": "2024-01-02T00:00:00Z" },
    "days"
]}
// Result: -1

// Unknown units are an error (catchable with try)
{ "date_diff": [
    { "datetime": "2024-01-02T00:00:00Z" },
    { "datetime": "2024-01-01T00:00:00Z" },
    "weeks"
]}
// Result: error (Invalid Arguments)

// With variables
{ "date_diff": [
    { "var": "end" },
    { "var": "start" },
    "days"
]}
// Data: {
//   "start": "2024-01-01T00:00:00Z",
//   "end": "2024-01-15T00:00:00Z"
// }
// Result: 14

// Check if within 24 hours
{ "<": [
    { "date_diff": [{ "now": [] }, { "var": "timestamp" }, "hours"] },
    24
]}
// Data: { "timestamp": "2024-01-15T10:00:00Z" }
// Result: true or false

// Days since creation
{ "date_diff": [
    { "now": [] },
    { "var": "createdAt" },
    "days"
]}

Try it:

DateTime Patterns

Check if date is in the past

{ "<": [{ "var": "date" }, { "now": [] }] }

Check if date is in the future

{ ">": [{ "var": "date" }, { "now": [] }] }

Check if within time window

{ "and": [
    { ">=": [{ "now": [] }, { "var": "startTime" }] },
    { "<=": [{ "now": [] }, { "var": "endTime" }] }
]}

Add days to a date

{ "+": [
    { "var": "date" },
    { "timestamp": "7d" }
]}

Calculate days until expiration

{ "date_diff": [
    { "var": "expiresAt" },
    { "now": [] },
    "days"
]}

Check if expired

{ "<": [{ "var": "expiresAt" }, { "now": [] }] }

See Also

• Arithmetic Operators — +, -, *, and / with datetimes and durations
• Comparison Operators — <, <=, >, >=, and == on timestamps and durations
• Error Handling Operators — catch invalid date or timezone formats with try
• Operators Overview — full operator catalog and feature-flag table

Missing Value Operators

Operators for checking whether data fields are absent.

Feature flags (Rust crate). missing and missing_some are baseline: every build has them. See the feature table.

missing

Check for missing fields in the data.

Syntax:

{ "missing": [key1, key2, ...] }
{ "missing": key }

Arguments:

• key1, key2, … - Field names to check. An argument that is an array of names, or an expression that evaluates to one, adds each of them: { "missing": [["a", "b"], "c"] } checks a, b and c

Returns: Array of missing field names.

Examples:

// Check single field
{ "missing": "name" }
// Data: { "age": 25 }
// Result: ["name"]

// Check multiple fields
{ "missing": ["name", "email", "phone"] }
// Data: { "name": "Alice", "phone": "555-1234" }
// Result: ["email"]

// All fields present
{ "missing": ["name", "age"] }
// Data: { "name": "Alice", "age": 25 }
// Result: []

// All fields missing
{ "missing": ["name", "age"] }
// Data: {}
// Result: ["name", "age"]

// Nested fields
{ "missing": ["user.name", "user.email"] }
// Data: { "user": { "name": "Alice" } }
// Result: ["user.email"]

// A key that exists with a null value counts as present
{ "missing": ["x"] }
// Data: { "x": null }
// Result: []

Notes:

• missing reports only absent paths. A key that exists with a null or empty-string value counts as present, so { "missing": ["x"] } with { "x": null } or { "x": "" } returns []. This differs from json-logic-js, which also reports keys whose value is null or ""
• Dot-separated names walk nested objects ("user.email"), and numeric segments index arrays ("items.0")
• Under MissingVar::Error (see Missing Variables), missing and missing_some still return the absent paths; they never raise VariableNotFound

Common Patterns

Require all fields:

{ "!": { "missing": ["name", "email", "password"] } }
// Returns true only if all fields are present

Check if any field is missing:

{ "!!": { "missing": ["name", "email"] } }
// Returns true if ANY field is missing

Conditional validation:

{ "if": [
    { "missing": ["required_field"] },
    { "throw": "Missing required field" },
    "ok"
]}

Try it:

missing_some

Require that at least N of a set of fields are present; returns the missing ones only when fewer than N are present.

Syntax:

{ "missing_some": [minimum, [key1, key2, ...]] }

Arguments:

• minimum - Minimum number of fields that should be present
• [key1, key2, ...] - Array of field names to check

Returns: Array of missing field names if fewer than minimum are present, empty array otherwise.

Examples:

// Need at least 1 of these contact methods
{ "missing_some": [1, ["email", "phone", "address"]] }
// Data: { "email": "a@b.com" }
// Result: [] (1 present, requirement met)

// Data: {}
// Result: ["email", "phone", "address"] (0 present, need at least 1)

// Need at least 2 of these
{ "missing_some": [2, ["name", "email", "phone"]] }
// Data: { "name": "Alice" }
// Result: ["email", "phone"] (only 1 present, need 2)

// Data: { "name": "Alice", "email": "a@b.com" }
// Result: [] (2 present, requirement met)

// Data: { "name": "Alice", "email": "a@b.com", "phone": "555" }
// Result: [] (3 present, exceeds requirement)

Notes:

• Presence follows the same rule as missing: a key holding null or "" counts as present
• A fractional minimum rounds up: 2.5 needs 3 present fields. A minimum of 0 or less is always met. A minimum that is not a number ("2", null, true) counts as 1
• A minimum larger than the number of listed fields cannot be met, so the result lists every absent field
• With fewer than two arguments ({ "missing_some": [1] }) the result is []

Common Patterns

Require at least one contact method:

{ "!": { "missing_some": [1, ["email", "phone", "fax"]] } }
// Returns true if at least one contact method is provided

Flexible field requirements:

{ "if": [
    { "missing_some": [2, ["street", "city", "zip", "country"]] },
    "Please provide at least 2 address fields",
    "Address accepted"
]}

Require majority of fields:

{ "!": { "missing_some": [3, ["field1", "field2", "field3", "field4", "field5"]] } }
// Returns true if at least 3 of 5 fields are present

Try it:

Comparison: missing vs missing_some

Integration with Validation

Form validation example:

{ "if": [
    { "missing": ["username", "password"] },
    { "throw": "VALIDATION_ERROR" },
    { "if": [
        { "missing_some": [1, ["email", "phone"]] },
        { "throw": "CONTACT_REQUIRED" },
        "valid"
    ]}
]}

Conditional field requirements:

// If business account, require company name
{ "if": [
    { "==": [{ "var": "accountType" }, "business"] },
    { "!": { "missing": ["companyName", "taxId"] } },
    true
]}

See Also

• Variable Access — var, val, and exists for reading and checking single paths
• Error Handling Operators — pair missing with throw and try in validation pipelines
• Configuration — configure MissingVar::Error to fail on absent var reads
• Coming from json-logic-js — how missing differs on null and "" fields
• Operators Overview — full operator catalog and feature-flag table

Error Handling Operators

Operators for throwing and catching errors inside a rule.

Feature flag (Rust crate). try and throw require the error-handling feature. Every language binding enables it. See the feature table.

Argument counts: try takes one or more arguments ({ "try": [] } is null, and a single argument evaluates as itself with nothing caught). throw reads one argument; with none it throws { "type": "null" }.

try

Catch errors and provide fallback values.

Syntax:

{ "try": [expression, fallback] }
{ "try": [expression, catch_expression] }
{ "try": [expression, fallback1, fallback2, ...] }

Arguments:

• expression - Expression that might throw an error
• fallback - Value or expression to use if an error occurs
• try tries further arms in order: each arm runs only if every arm before it raised an error. Only the last arm evaluates with the error object as its context; intermediate arms see the ordinary data context

Returns: Result of expression if successful, or fallback value/expression result if an error occurs.

What counts as an error:

• Anything raised by throw.
• Errors raised by the engine itself: an unknown operator, invalid arguments (for example { "max": ["a", 1] }), an integer division by zero, a datetime that fails to parse, an unknown timezone, and so on.
• A missing variable is not an error under the default configuration: var and val return null for an absent path, so try does not fall back on missing data. Use ?? or var’s default argument for that (see Control Flow). An engine configured with EvaluationConfig::missing_var set to MissingVar::Error raises VariableNotFound instead, and try catches it like any other error (see Missing Variables).
• An exhausted operation budget (BudgetExceeded) is final: try passes it on without running a fallback arm.

Context in Catch: When try catches an error, the catch expression evaluates with the error object as its context, so you read its fields via var / val:

• A string throw produces the error object { "type": <string> }, so you read the message with { "var": "type" }.
• An object throw (sourced from data) preserves its own keys, so fields such as { "var": "code" } or { "var": "message" } read those keys.
• Any other thrown value becomes { "type": <its type name> }: { "throw": 5 } gives { "type": "number" }.
• Engine-raised errors arrive as { "type": <message> }: an unknown operator gives { "type": "Unknown Operator" }, bad operands give { "type": "Invalid Arguments" }, an integer division by zero gives { "type": "NaN" }, and other kinds carry their message text (for example { "type": "Invalid datetime format" }, { "type": "Unknown timezone: Mars/Olympus" }, or, under MissingVar::Error, { "type": "Variable not found: user.name" }).
• { "var": "" } returns the entire error object.

Examples:

// Simple fallback value
{ "try": [
    { "/": [10, 0] },
    0
]}
// Result: 0 (division by zero caught)

// Expression that succeeds
{ "try": [
    { "+": [1, 2] },
    0
]}
// Result: 3 (no error, normal result)

// Catch a string error: the string becomes the error object's "type" field
{ "try": [
    { "throw": "User not found" },
    { "cat": ["Error: ", { "var": "type" }] }
]}
// Result: "Error: User not found"

// Canonical pattern: read a thrown string back via "type"
{ "try": [
    { "throw": "Some error" },
    { "val": "type" }
]}
// Result: "Some error"

// Throw an object sourced from data, then read its fields by key
{ "try": [
    { "throw": { "var": "err" } },
    { "var": "code" }
]}
// Data: { "err": { "code": 404, "message": "User not found" } }
// Result: 404

// Engine errors are caught too: read the kind via "type"
{ "try": [{ "not_an_operator": [1] }, { "var": "type" }] }
// Result: "Unknown Operator"

{ "try": [{ "max": ["a", 1] }, { "var": "type" }] }
// Result: "Invalid Arguments"

// Multiple fallback arms: each runs only if the previous one raised
{ "try": [{ "throw": "a" }, { "throw": "b" }, "c"] }
// Result: "c"

// A missing variable is NOT an error, so try does not fall back
{ "try": [{ "var": "missing" }, "fallback"] }
// Data: {}
// Result: null

// Nested try: the inner arm re-throws a clearer message, the outer arm reads it
{ "try": [
    { "try": [
        { "/": [1, { "var": "d" }] },
        { "throw": "division failed" }
    ]},
    { "var": "type" }
]}
// Data: { "d": 0 }
// Result: "division failed"

// Data: { "d": 4 }
// Result: 0.25

Common Patterns

Safe division:

{ "if": [
    { "!": { "var": "denominator" } },
    0,
    { "/": [{ "var": "numerator" }, { "var": "denominator" }] }
]}
// Data: { "numerator": 1 }
// Result: 0

// Data: { "numerator": 1, "denominator": 4 }
// Result: 0.25

try alone is not enough here. Only an integral-valued zero divisor (or a non-numeric string) raises the NaN error that try can catch. A null, false, "", or "0" divisor coerces to zero and follows EvaluationConfig::division_by_zero, whose default (ReturnSaturated) returns f64::MAX without raising, so { "try": [{ "/": [{ "var": "numerator" }, { "var": "denominator" }] }, 0] } yields 1.7976931348623157e308 when denominator is missing. Configure DivisionByZeroHandling::ThrowError if you want every zero divisor to reach the try fallback; see Arithmetic for the full rule.

Default for a missing value (not a try job):

{ "??": [{ "var": "user.profile.settings.theme" }, "default-theme"] }
// Data: {}
// Result: "default-theme"

Under the default configuration var on a missing path returns null rather than raising, so wrapping it in try never produces the fallback. Use ?? or the var default form, { "var": ["user.profile.settings.theme", "default-theme"] }.

Error logging pattern:

{ "try": [
    { "risky_operation": [] },
    { "cat": ["Operation failed: ", { "var": "type" }] }
]}
// Result: "Operation failed: Unknown Operator"
// risky_operation stands in for a custom operator. In the default engine the
// name is not registered, so the call itself raises "Unknown Operator" and is
// caught. For a string throw, the thrown text is in the "type" field; if the
// operation throws a structured object instead, read the relevant key (e.g.
// "message").

Try it:

throw

Throw an error with optional details.

Syntax:

{ "throw": message }
{ "throw": error_object }

Arguments:

• message - Error message string. The string becomes the error object’s type field, or
• error_object - An error object value (sourced from data, or built in templating mode) with arbitrary keys such as code and message. A multi-key object written inline as a literal does NOT compile in the default engine, because the engine parses it as an operator map. A single-key literal such as { "throw": { "type": "X" } } does not work either, even in templating mode: type is an operator name, so it runs the type operator on "X" and throws { "type": "string" }. An error object carrying a type key must come from data ({ "throw": { "var": "err" } }).

Returns: Never returns normally. The error ends the evaluation unless a try catches it.

Examples:

// Simple string error (the string lands in the error object's "type" field)
{ "throw": "Something went wrong" }
// Throws the error object { "type": "Something went wrong" }

// Error object sourced from data. A literal multi-key object written inline
// would be parsed as an operator map and fail to compile in the default engine.
{ "throw": { "var": "err" } }
// Data: { "err": { "code": "INVALID_INPUT", "message": "Age must be positive" } }
// Throws an error carrying the object's fields

// Richer error: build the object in your data (or enable templating mode) and
// throw it by reference.
{ "throw": { "var": "validationError" } }
// Data: {
//   "validationError": {
//     "code": "VALIDATION_ERROR",
//     "message": "Invalid email format",
//     "field": "email"
//   }
// }

// Conditional throw (string form)
{ "if": [
    { "<": [{ "var": "age" }, 0] },
    { "throw": "Age cannot be negative" },
    { "var": "age" }
]}
// Data: { "age": -5 }
// Throws the error object { "type": "Age cannot be negative" }

// Data: { "age": 25 }
// Result: 25

Uncaught errors

An error that no try catches reaches your code as an Error. A throw arrives with ErrorCode::Thrown (tag "Thrown") and the error object as its payload (Error::thrown_value()). Error::operator() names the innermost operator that failed (since 5.8.0), here throw, on every evaluation path, traced or not. The serialized form of the error from { "+": [1, { "throw": "bad" }] }:

{"type": "Thrown", "message": "Thrown: {\"type\":\"bad\"}", "thrown": {"type": "bad"}, "operator": "throw", "node_ids": [3, 4]}

See Error in the API reference for the other fields.

Common Patterns

Validation with throw:

{ "if": [
    { "missing": ["name", "email"] },
    { "throw": "Required fields missing" },
    "valid"
]}

Business rule enforcement:

{ "if": [
    { ">": [{ "var": "amount" }, { "var": "balance" }] },
    { "throw": "Amount exceeds balance" },
    { "-": [{ "var": "balance" }, { "var": "amount" }] }
]}

Type validation:

{ "if": [
    { "!==": [{ "type": { "var": "value" } }, "number"] },
    { "throw": "Expected number" },
    { "*": [{ "var": "value" }, 2] }
]}

Try it:

Error Handling Patterns

Graceful Degradation

Fallback chains over possibly-missing data belong to ??, not try, because a missing var is null rather than an error:

{ "??": [
    { "var": "user.preferences.language" },
    { "var": "defaults.language" },
    "en"
]}
// Data: { "defaults": { "language": "fr" } }
// Result: "fr"

// Data: {}
// Result: "en"

Reserve try for expressions that can raise: throw, an integer division by zero, invalid arguments, an unknown operator, a datetime parse failure.

Validation Pipeline

{ "try": [
    { "if": [
        { "!": { "var": "input" } },
        { "throw": "Input required" },
        { "if": [
            { "<": [{ "length": { "var": "input" } }, 3] },
            { "throw": "Minimum 3 characters" },
            { "var": "input" }
        ]}
    ]},
    { "cat": ["Validation error: ", { "var": "type" }] }
]}
// Data: {}
// Result: "Validation error: Input required"

// Data: { "input": "ab" }
// Result: "Validation error: Minimum 3 characters"

// Data: { "input": "abc" }
// Result: "abc"

Error Recovery with Fallback Operations

The variadic form tries each arm in turn:

{ "try": [
    { "primary_operation": [] },
    { "fallback_operation": [] },
    "all operations failed"
]}
// Result: "all operations failed"
// primary_operation and fallback_operation stand in for custom operators. Each
// arm runs only if the previous one raised; in the default engine neither name
// is registered, so both raise "Unknown Operator" and the last arm is returned.

Collecting All Errors

JSONLogic has no native way to collect multiple errors, but you can structure validations to report every failure:

{ "filter": [
    [
        { "if": [{ "missing": ["name"] }, "name is required", null] },
        { "if": [{ "missing": ["email"] }, "email is required", null] },
        { "if": [
            { "and": [
                { "!": { "missing": ["email"] } },
                { "!": { "in": ["@", { "var": "email" }] } }
            ]},
            "invalid email format",
            null
        ]}
    ],
    { "!==": [{ "var": "" }, null] }
]}
// Data: { "email": "foo" }
// Result: ["name is required", "invalid email format"]

This returns an array of error messages for all validation failures. To wrap it in an object such as { "errors": [...] }, enable templating mode (Engine::builder().with_templating(true), Cargo feature templating). The default engine parses a top-level errors key as an operator call, which fails with InvalidOperator.

See Also

• Control Flow Operators — use ?? and if for null-coalescing and branching without throwing
• Missing Value Operators — check for required fields before throwing validation errors
• Configuration — configure NanHandling, DivisionByZeroHandling, and MissingVar
• Structured Objects (Templating) — build structured error payloads in rules
• Operators Overview — full operator catalog and feature-flag table

Tensor Operators

JSON has no tensor. Anything that marshals JSON into a model’s inputs and its outputs back into JSON (an ONNX Runtime session, an edge request encoder, an RL observation buffer) needs one value that is neither a scalar nor a JSON array. The tensor feature adds it: an opaque n-dimensional typed buffer (a dtype, a shape, and one row-major contiguous byte payload), plus twenty operators that make, reshape, and read one back.

Feature flags (Rust crate). All tensor operators require the tensor feature. tensor-half also enables f16 / bf16 elements. Every language binding enables tensor but not tensor-half. See the feature table.

Argument counts: each section’s syntax lists every argument an operator reads, optional ones included. to_list, shape and dtype take one; zeros, stack, concat, unstack, reshape, cast and argmax two; full, rle_expand, one_hot and crop three; tensor and transpose one or two; normalize and gather two or three; scatter and pad three or four. See Errors and limits for a call with the wrong count.

What this is not

There is no arithmetic here: no matmul, no convolution, no element-wise add. The family marshals data and nothing else. Every operator’s cost is proportional to the data it moves, which is what keeps it honest to price; an operator whose work is not proportional to its data (a matmul reads 2n² elements and does n³ multiplies) would break that property. Model execution belongs in the runtime you are feeding, not in the rules engine.

The wire form

A tensor crosses the JSON boundary as a single-key tagged object:

{ "tensor": { "dtype": "f32", "shape": [2, 2], "data": "AACAPwAAAEAAAEBAAACAQA==" } }

data is the raw little-endian payload in standard base64. This one form is the operator call, the form the engine emits, and the form the decoder accepts, so a serialized tensor pasted back into a rule evaluates to the tensor it came from, and a tensor stored in your input data decodes with {"tensor": [{"val": "..."}]}.

Because the text-returning bindings (WASM, Node, C and everything built on it) hand back JSON, tensors flow through them unchanged with no FFI change.

dtypes

bool, i8, u8, i16, u16, i32, u32, i64, u64, f16, bf16, f32, f64. Names match case-insensitively, so safetensors-style "F32" works.

The shape operators (stack, concat, unstack, reshape, transpose, pad, crop, gather) move raw cells and never interpret one, so they work on every dtype including f16 / bf16 with no extra feature. zeros does too: an all-zero buffer is a valid value of every dtype. The element operators need tensor-half before they will touch f16 / bf16, and answer an unsupported-dtype error otherwise.

tensor

Build a tensor, or pass one through. The family’s entry point.

Syntax:

{ "tensor": [value, dtype] }
{ "tensor": [value] }

Arguments:

• value: nested JSON arrays (or a bare scalar for a 0-d tensor), the tagged wire form, or an existing tensor
• dtype: required for the nested-array form; the shape is inferred from the nesting

Returns: A tensor.

An element that does not fit the declared dtype (300 as u8) is an error; the operator does not truncate it or replace it with an infinity.

Examples:

{ "tensor": [[[1, 2], [3, 4]], "f32"] }
// Result: a 2x2 f32 tensor

{ "tensor": [{ "val": "prediction" }] }
// Decodes a tagged tensor out of the input data

{ "reshape": [{ "tensor": [[1, 2, 3, 4], "u8"] }, [2, 2]] }
// A flat list plus a shape

zeros / full

Build a tensor of a declared shape.

Syntax:

{ "zeros": [shape, dtype] }
{ "full": [shape, dtype, value] }

Examples:

{ "zeros": [[2, 3], "i32"] }        // 2x3 of 0
{ "full": [[2, 2], "f32", 1.5] }    // 2x2 of 1.5

scatter

Sparse writes into an otherwise-zero tensor.

Syntax:

{ "scatter": [points, shape, dtype, value] }

Arguments:

• points: array of coordinate arrays. [i, j] writes value (1 by default); [i, j, v] writes v
• value: optional default written value

scatter drops an out-of-range point without an error: the usual producer is a detector emitting boxes in source coordinates that may fall outside the target grid.

Examples:

{ "scatter": [[[0, 1], [1, 0]], [2, 2], "u8"] }
// [[0, 1], [1, 0]]

rle_expand

Run-length decode into a tensor, row-major.

Syntax:

{ "rle_expand": [runs, shape, dtype] }

runs is the flat [v0, n0, v1, n1, …] pairing. The run lengths must sum to exactly the shape’s element count. A mask that decodes to the wrong size is a producer bug, and zero-filling the remainder would hide it.

Examples:

{ "rle_expand": [[0, 2, 1, 2], [2, 2], "u8"] }
// [[0, 0], [1, 1]]

one_hot

Build a [len, depth] indicator matrix.

Syntax:

{ "one_hot": [indices, depth, dtype] }

An index outside 0..depth leaves its row all-zero.

Examples:

{ "one_hot": [[0, 2], 3, "u8"] }
// [[1, 0, 0], [0, 0, 1]]

stack / concat / unstack

Join and split along an axis. stack introduces a new axis (so the result is one rank higher); concat joins along an existing one. unstack is the inverse of stack. Negative axes count from the end.

Syntax:

{ "stack": [tensors, axis] }
{ "concat": [tensors, axis] }
{ "unstack": [tensor, axis] }

stack requires identical shapes; concat requires them to agree on every axis but the joined one. Both require a common dtype. unstack returns an array of tensors.

Examples:

{ "stack": [[{"tensor": [[1, 2], "u8"]}, {"tensor": [[3, 4], "u8"]}], 0] }
// A 2x2 tensor: [[1, 2], [3, 4]]

reshape

Reinterpret the same bytes under a new shape. The only operator here that copies nothing: the output shares its payload with the input.

Syntax:

{ "reshape": [tensor, shape] }

The element count must match exactly; there is no inferred -1 dimension.

transpose

Permute the axes. perm defaults to a full reversal, so a 2-d transpose needs no second argument.

Syntax:

{ "transpose": [tensor] }
{ "transpose": [tensor, perm] }

pad / crop

Grow or cut every axis. crop is the inverse of pad.

Syntax:

{ "pad": [tensor, before, after, value] }
{ "crop": [tensor, offset, shape] }

before and after take one entry per axis. value defaults to 0. A crop window must lie inside the input.

Examples:

{ "pad": [{ "tensor": [[1, 2], "u8"] }, [1], [2]] }
// [0, 1, 2, 0, 0]

gather

Select slices along an axis, in the order given, so it both reorders and resamples.

Syntax:

{ "gather": [tensor, indices, axis] }

axis defaults to 0. Negative indices count from the end. Every index must be in range: unlike scatter, dropping one would change the output shape without an error.

cast

Convert to another dtype. cast is the family’s only cross-dtype conversion, and it is lossy.

Syntax:

{ "cast": [tensor, dtype] }

Narrowing saturates rather than wrapping (300 to u8 is 255, not 44), and NaN becomes 0. cast converts each value through f64, so i64 / u64 elements above 2^53 lose their low bits. Casting to the dtype a tensor already has returns it unchanged, with no trip through f64.

normalize

(x − mean) × scale, always producing f32.

Syntax:

{ "normalize": [tensor, mean, scale] }

scale defaults to 1, so the two-argument form is a plain mean subtraction. The output dtype is fixed because that is what the operation is for: turning integer sensor or pixel data into the float range a model expects. mean and scale are scalars; per-channel normalization is unstack + normalize + stack.

Examples:

{ "normalize": [{ "tensor": [[0, 255], "u8"] }, 127.5, 0.5] }
// [-63.75, 63.75]

argmax

Index of the largest element along an axis, as plain JSON.

Syntax:

{ "argmax": [tensor, axis] }

Returns: Nested JSON arrays of indices, or a bare number when the input is 1-d. An index is something a rule goes on to compare and branch on, so it comes back as ordinary JSON rather than a tensor.

Ties go to the first occurrence, and NaN never wins.

Examples:

{ "argmax": [{ "tensor": [[[1, 9], [7, 3]], "f32"] }, 1] }
// [1, 0]

to_list

Expand into plain nested JSON arrays.

Syntax:

{ "to_list": [tensor] }

The general escape hatch, and expensive by design: this is the one operator that turns a compact buffer back into one JSON node per element. Reach for argmax, shape or a comparison first.

shape / dtype

Read the header.

Syntax:

{ "shape": [tensor] }
{ "dtype": [tensor] }

shape returns an array of numbers; dtype returns the wire name, which is exactly what tensor, zeros, full and cast accept back.

Errors and limits

• Argument count. Every tensor operator checks its argument count before it evaluates any argument: too few raises missing argument, too many raises too many arguments (both InvalidArguments).
• Size cap. zeros, full, scatter, rle_expand, one_hot and pad size a new buffer from dimensions in the rule. Past 2^28 (268,435,456) elements, 2 GiB of f64, they raise InvalidArguments("tensor would hold more than 268435456 elements") before allocating, so {"zeros": [[1000000, 1000000], "f64"]} fails fast on an engine without an operation budget.
• Two problems in one call. The arguments are evaluated in order, and an error raised while evaluating a later argument wins over a coercion error on an earlier one: {"zeros": ["bad", {"throw": "x"}]} throws x.

How a tensor behaves as a value

Tensor operators are never constant-folded and never memoized by the CSE pass, even though they are pure functions of their arguments: folding {"zeros": [[128, 128], "f32"]} would bake a 64 KB literal into the compiled rule.

See Also

• Array Operators — manipulate ordinary JSON arrays before converting with tensor or after to_list
• Operation Budget — how tensor operations charge per element
• Configuration — enable or disable Family::Tensor at runtime
• Operators Overview — full operator catalog and feature-flag table

flagd-Compat Operators

Two operators specified by the OpenFeature flagd in-process provider (fractional, semantic version) for feature-flag targeting. The implementation follows the canonical Go evaluator, so a flag definition that works under a flagd provider picks the same variants here.

Feature flag (Rust crate). fractional and sem_ver require the flagd feature (off by default in the Rust crate; enabled in every language binding). An engine built with EngineBuilder::with_families includes them only when Family::Flagd is listed. See the feature table.

datalogic-rs = { version = "5", features = ["flagd"] }

Argument counts: fractional takes one or more arguments; sem_ver takes exactly three.

Both operators return null on malformed input (a wrong argument count, an unparseable version, a missing targeting key, a bucket that is not a [variant, weight] array) rather than raising. flagd’s evaluator observes the null and falls back to the flag’s default variant; non-flagd callers can compose with ?? or if for the same effect. An error raised while evaluating an argument, such as a throw, still propagates.

fractional

Deterministic percentage bucketing for A/B tests and gradual rollouts. Buckets are sticky per bucketing key: the same input always lands in the same variant across runs.

Reference: flagd Fractional spec

Algorithm. MurmurHash3 x86-32 of the bucketing key, then bucket = (hash * total_weight) >> 32 and walk cumulative integer weight bands, as the Go evaluator’s core/pkg/evaluator/fractional.go does. The crate vendors the hash, so the feature adds no hashing dependency.

Two argument shapes:

1. Explicit bucketing key

The first argument evaluates to a string; the remaining args are [variant, weight] pairs.

{
  "fractional": [
    { "cat": [{ "var": "$flagd.flagKey" }, { "var": "email" }] },
    ["red",   50],
    ["blue",  20],
    ["green", 30]
  ]
}

The canonical pattern concatenates $flagd.flagKey + email so the same email gets different variants on different flags, and a user isn’t locked into one cohort across your whole product.

2. Implicit bucketing key

Omit the first argument, or let it evaluate to null (for example a missing var). The operator parses any other non-string first argument, such as a number or boolean, as a bucket definition; since that argument is not an array, the whole call returns null. The bucketing key is built from the root context as flagKey + targetingKey (the order the flagd Go evaluator uses):

{
  "fractional": [
    ["new-ui", 50],
    ["old-ui", 50]
  ]
}

targetingKey (a non-empty string) is required. $flagd.flagKey is optional: when it is absent the key is the targetingKey alone, which still buckets deterministically but loses the per-flag cohort separation. flagd in-process providers stamp both onto the context as:

{
  "targetingKey": "alice@example.com",
  "$flagd": { "flagKey": "header-color" }
}

Missing, empty, or non-string targetingKey in implicit form returns null: there’s no key to hash and flagd’s contract is to fall back to the default variant.

Weights

Weights are relative, not percentages: [50, 50] and [1, 1] produce identical splits because the operator divides by the total. This lets you grow a rollout from [1, 99] to [50, 50] to [99, 1] without renormalizing.

Weights must be non-negative integers. Omitted weights default to 1, so ["red"], ["blue"] is equivalent to ["red", 1], ["blue", 1]. A non-integer weight (a fraction such as 99.9, or a string such as "50") also falls back to 1, so [["a", 99.9], ["b", 0.1]] behaves exactly like [["a", 1], ["b", 1]]. Negative weights clamp to 0, and weights above i32::MAX (2,147,483,647) clamp to it, since flagd’s weights are 32-bit: two equal weights of 2^40 split like [1, 1]. If every weight is 0, the call returns null.

Composing with if

To bucket only the users who pass a precondition, put fractional in a branch of if:

{
  "if": [
    { "in": ["@example.com", { "var": "email" }] },
    {
      "fractional": [
        { "cat": [{ "var": "$flagd.flagKey" }, { "var": "email" }] },
        ["new-ui", 50],
        ["old-ui", 50]
      ]
    },
    "old-ui"
  ]
}

sem_ver

Semantic-version comparison with the four normalizations the flagd spec calls for.

Reference: flagd SemVer spec

Syntax:

{ "sem_ver": [version1, operator, version2] }

Operators:

Comparison follows SemVer 2.0 precedence, including pre-release ordering: 1.0.0-alpha < 1.0.0-beta < 1.0.0.

Input normalizations

The operator applies four normalizations to both version arguments before parsing, matching what the flagd evaluator and most other flagd providers do:

1. Strip leading v / V: "v1.2.3", "V1.2.3", and "1.2.3" are all equivalent.
2. Pad partial versions: "1" becomes "1.0.0", "1.2" becomes "1.2.0".
3. Coerce numeric input: 1 (a JSON number) is treated as the string "1", then padded.
4. Drop build metadata: "1.2.3+build.7" is treated as "1.2.3". (SemVer 2.0 specifies build metadata is ignored when determining precedence.)

Examples

// Simple comparison
{ "sem_ver": [{ "var": "app_version" }, ">=", "1.2.0"] }

// Caret: same major
{ "sem_ver": [{ "var": "app_version" }, "^", "1.0.0"] }
// matches 1.0.0, 1.5.3, 1.99.99, but not 2.0.0

// Tilde: same major + minor
{ "sem_ver": [{ "var": "app_version" }, "~", "1.2.0"] }
// matches 1.2.0, 1.2.5, 1.2.99, but not 1.3.0

// v-prefixed input is handled transparently
{ "sem_ver": ["v1.2.3", "=", "1.2.3"] }            // true
{ "sem_ver": ["1.2", "<", "1.2.1"] }                // true (1.2 padded to 1.2.0)
{ "sem_ver": [1, "=", "v1.0.0"] }                   // true (int 1 coerced)

Gated rollout pattern

The common shape for shipping a feature only to clients on a recent version:

{
  "if": [
    { "sem_ver": [{ "var": "app_version" }, ">=", "2.0.0"] },
    { "fractional": [
        { "cat": [{ "var": "$flagd.flagKey" }, { "var": "user_id" }] },
        ["new-checkout", 10],
        ["old-checkout", 90]
    ]},
    "old-checkout"
  ]
}

Conformance

The conformance test suites live under crates/datalogic-rs/tests/suites/flagd/ and mirror the upstream Go test fixtures:

• fractional_test.go
• semver_test.go

The release workflow runs the full suite on the tag before it publishes.

See Also

• Control Flow Operators — combine fractional and sem_ver with if and ??
• String Operators — build bucketing keys with cat
• Use Cases & Examples — feature flag and rollout rule patterns
• Operators Overview — full operator catalog and feature-flag table

Rust (Native Crate)

datalogic-rs is the core: it implements everything the other bindings expose. Using the crate directly gives you the full API ladder, including the zero-copy tier no wrapper exposes.

Install

cargo add datalogic-rs

The default build has no dependency on serde_json and ships the 33 baseline operators. Opt into features as needed; all-operators turns on every operator family at once:

[dependencies]
datalogic-rs = { version = "5", features = ["all-operators", "serde_json", "templating", "trace"] }

See the feature matrix for what each flag adds.

Quick start

let result = datalogic_rs::eval_str(
    r#"{">": [{"var": "x"}, 10]}"#,
    r#"{"x": 42}"#,
).unwrap();
assert_eq!(result, "true");

A default engine backs the module-level helpers (eval, eval_str, eval_into, compile), so one-off evaluation needs no setup.

Five tiers, one engine

Pick the tier that matches your performance budget and trace requirements:

Tiers 0 to 2 and the trace tier exist in every language binding; Tier 3 (caller-owned arena) is Rust-only.

Compile once, evaluate many

use datalogic_rs::Engine;

let engine = Engine::default();
let logic = engine.compile(r#"{">": [{"var": "x"}, 10]}"#).unwrap();

let mut session = engine.session();
for payload in inputs {
    let result = session.eval_str(&logic, payload).unwrap();
}

Compiled Logic is Send + Sync: share it across threads via Arc (or Engine::compile_arc). A Session is Send but not Sync; open one per thread or task. To keep a session in a struct or hold it across an .await, use SharedSession, which holds the engine by Arc. See Thread Safety for Tokio and rayon patterns.

Inspecting rules

Before a rule runs, Engine::check lists every problem the engine can see in it, and Engine::compile_checked refuses a rule with errors. After compiling, Logic::facts reports the data paths the rule reads and the operators it calls, and Engine::operators describes every built-in operator. See Rule Analysis.

Where everything else is documented

• API Reference: the public types, methods, and error variants
• Starter Boilerplates: copy-paste Axum feature-flag endpoint
• docs.rs/datalogic-rs: rustdoc with feature badges
• Crate README: the deep-dive with per-tier performance profiles
• Runnable examples: ten CI-built examples from getting started to zero-copy input
• Custom Operators · Configuration · Rule Analysis · Operation Budget · Structured Objects · Thread Safety · Security & Sandboxing

API Reference

Core types and methods of the datalogic-rs crate, 5.9.0. For every item and its feature badge, see docs.rs/datalogic-rs.

Public surface at a glance

The crate exposes five evaluation tiers, in order of caller control. Most callers want Tier 0 for ad-hoc work or Tier 2 for repeated evaluation.

Every binding exposes the same tier model; see each binding’s README for the language-idiomatic entry points.

Module-level helpers

For the simplest cases, skip the engine entirely:

let result = datalogic_rs::eval_str(
    r#"{"==": [{"var": "x"}, 1]}"#,
    r#"{"x": 1}"#,
).unwrap();
assert_eq!(result, "true");

pub fn compile<R: IntoLogic>(rule: R) -> Result<Logic>;
pub fn eval<R, D>(rule: R, data: D) -> Result<OwnedDataValue>;
pub fn eval_str<R, D>(rule: R, data: D) -> Result<String>;

#[cfg(feature = "serde_json")]
pub fn eval_into<T, R, D>(rule: R, data: D) -> Result<T>;

These delegate to a shared default engine (lazy OnceLock<Engine>). Build your own Engine when you need custom operators, a non-default config, templating, or a long-lived Session.

Engine

The configured engine. Compiles rules and evaluates them. Engine is Send + Sync; share one through an Arc.

Creating an Engine

use datalogic_rs::{Engine, EvaluationConfig};

// Default engine.
let engine = Engine::new();

// Builder: set config, enable templating, register custom operators.
let engine = Engine::builder()
    .with_config(EvaluationConfig::strict())
    .with_templating(true)           // requires feature = "templating"
    .with_template_key_escape('$')   // optional: `{"$type": ...}` emits the key `type`
    .add_operator("my_op", MyOperator)
    .with_constant_folding(true)     // default; pass false to keep every operator visible in the compiled tree
    .build();

Operator registration is builder-only: the Engine that build() returns has a fixed operator set. See EngineBuilder.

Methods

compile

Compile a JSONLogic rule into reusable Logic.

pub fn compile<R: IntoLogic>(&self, rule: R) -> Result<Logic>;
pub fn compile_arc<R: IntoLogic>(&self, rule: R) -> Result<Arc<Logic>>;
pub fn compile_strict<R: IntoLogic>(&self, rule: R) -> Result<Logic>;
#[cfg(feature = "templating")]
pub fn compile_template<R: IntoLogic>(&self, rule: R) -> Result<Logic>;

compile uses the engine’s templating mode. compile_strict and compile_template choose the mode for one compile instead, with the engine’s custom operators, template key escape and folding setting, so one engine can check a rule strictly and compile an output template. compile_strict exists in every build; on an engine without templating it is compile.

R: IntoLogic accepts &str (JSON-parsed), &String, &OwnedDataValue / OwnedDataValue, and &serde_json::Value (gated on feature = "serde_json"). compile_arc is Arc::new(engine.compile(rule)?) in one call, for sharing a rule across threads.

check / compile_checked

pub fn check<R: IntoLogic>(&self, rule: R, mode: CheckMode) -> Vec<Diagnostic>;
pub fn compile_checked<R: IntoLogic>(&self, rule: R) -> std::result::Result<Logic, CompileError>;

check reports every problem the engine can see in a rule before it runs, each located by a JSON Pointer. compile_checked compiles a rule only when check finds no error, and otherwise returns a CompileError listing every diagnostic. See Rule Analysis.

eval / eval_str / eval_into / eval_as (one-shot)

Engine-owned arena per call. They differ only in the result type:

pub fn eval<R, D>(&self, rule: R, data: D) -> Result<OwnedDataValue>;
pub fn eval_str<R, D>(&self, rule: R, data: D) -> Result<String>;
pub fn eval_as<O: FromDataValue, R, D>(&self, rule: R, data: D) -> Result<O>;

#[cfg(feature = "serde_json")]
pub fn eval_into<T, R, D>(&self, rule: R, data: D) -> Result<T>;

R: IntoLogic and D: OwnedInput: data accepts &str, &String, &OwnedDataValue / OwnedDataValue, &serde_json::Value (gated on serde_json), and Roots. An owned String is not accepted; pass &s. For eval_into, T: DeserializeOwned; the typical choices are serde_json::Value (JSON-shaped boundary) or your own domain struct. eval_as::<serde_json::Value> converts the result in one step where eval_into::<serde_json::Value> builds a value and deserialises it again.

let result = engine.eval_str(
    r#"{"+": [{"var": "x"}, 1]}"#,
    r#"{"x": 41}"#,
)?;
assert_eq!(result, "42");

let value: serde_json::Value = engine.eval_into(
    r#"{"+": [{"var": "x"}, 1]}"#,
    r#"{"x": 41}"#,
)?;

evaluate (raw tier)

Hot-path evaluation against arena-resident data. The caller owns the bumpalo::Bump; the result borrows from it.

pub fn evaluate<'a, D: EvalInput<'a>>(
    &self,
    compiled: &'a Logic,
    data: D,
    arena: &'a bumpalo::Bump,
) -> Result<&'a DataValue<'a>>;

D accepts any of: &'a DataValue<'a>, DataValue<'a>, &'a str, &'a String, &OwnedDataValue, &ParsedData (see ParsedData), &serde_json::Value (under feature = "serde_json"), or Roots.

use bumpalo::Bump;
use datalogic_rs::Engine;

let engine = Engine::new();
let compiled = engine.compile(r#"{"==": [{"var": "x"}, 1]}"#).unwrap();
let arena = Bump::new();
let result = engine.evaluate(&compiled, r#"{"x": 1}"#, &arena).unwrap();
assert_eq!(result.as_bool(), Some(true));

With feature = "budget", evaluate_metered(&compiled, data, &arena, budget) runs the same evaluation under an explicit operation budget and returns a Result<Metered<&DataValue>> (evaluate_metered_report returns a failure-inclusive Metered<Result<&DataValue>>; Session::eval_metered and Session::eval_metered_report are the session counterparts). See Operation Budget.

session

Open a Session that owns a reusable arena.

pub fn session(&self) -> Session<'_>;

For a session that holds the engine by Arc instead of borrowing it, use SharedSession.

truthy

Apply the engine’s configured TruthyEvaluator to an arena value. if, and, or, ! and !! apply the same coercion, so custom operators and callers of evaluate can decide truthiness the way the engine would.

pub fn truthy(&self, value: &DataValue<'_>) -> bool;

let compiled = engine.compile(r#"{"var": "items"}"#)?;
let arena = bumpalo::Bump::new();
let result = engine.evaluate(&compiled, r#"{"items": [1]}"#, &arena)?;
assert!(engine.truthy(result));

truthy_of

The same rules for a value in whatever representation the host holds: &serde_json::Value, &OwnedDataValue, &ParsedData or &DataValue (the sealed TruthyInput trait). Use it on an evaluated result instead of re-implementing truthiness: it follows the configured evaluator, and under the default rules an empty object is falsy, like an empty array.

pub fn truthy_of<V: TruthyInput>(&self, value: V) -> bool;

let result: serde_json::Value = session.eval_into(&compiled, &context)?;
if !engine.truthy_of(&result) {
    return Err(rejected());
}

trace (feature = “trace”)

Open a TracedSession that records execution steps. Every eval* on it returns a TracedRun<R> carrying the result, steps, and compile-time expression tree, with the same R that Session would return; the inputs differ from Session (see the Trace API section).

#[cfg(feature = "trace")]
pub fn trace(&self) -> TracedSession<'_>;

to_builder

pub fn to_builder(&self) -> EngineBuilder;

A builder holding this engine’s custom operators, config, templating mode, template key escape, folding setting and families. Change what differs and build a new engine; both share the operator instances. See Custom Operators: rebuilding an engine.

Introspection helpers

pub fn config(&self) -> &EvaluationConfig
pub fn has_custom_operator(&self, name: &str) -> bool
pub fn custom_operator_names(&self) -> impl Iterator<Item = &str>
pub fn custom_operator_info(&self, name: &str) -> Option<CustomOperatorInfo>
pub fn builtin_operator_names(&self) -> impl Iterator<Item = &'static str>
pub fn operators(&self) -> impl Iterator<Item = OperatorInfo>

operators() describes each built-in operator as its table row declares it: canonical name and aliases, family and gating feature, argument counts, whether it reads the data context, its effect, its cost class, and which argument (if any) runs under a pushed frame. See Rule Analysis.

builtin_operator_names() reports every built-in key this engine resolves as an operator: the baseline set plus the extension families the build compiled in and the engine kept (see Operator Families), including the input aliases var, ?: and match. It is derived from the compiler’s own lookup table, so it cannot drift from dispatch. Together with custom_operator_names() it is the engine’s full vocabulary, which authoring tools need under templating mode, where an unknown key is not an error but echoes back as data.

custom_operator_info(name) returns what a registered custom operator declares about itself through CustomOperator::info, or None when no custom operator has that name.

EngineBuilder

Fluent constructor for Engine. Returned by Engine::builder() (or Engine::to_builder()).

EngineBuilder::new()
    .with_config(EvaluationConfig::default())
    .with_templating(true)                  // feature = "templating"
    .with_template_key_escape('$')          // optional escape for operator-named template keys
    .with_constant_folding(true)            // default; disable to keep every operator visible
    .with_families([Family::ExtString])     // optional: the core plus these families
    .add_operator("name", MyOp)             // typed operator
    .add_operator("dyn", boxed_op)          // also accepts Box<dyn CustomOperator> or Arc<T>
    .try_add_operator("other", OtherOp)?    // Err if a built-in answers to the name
    .try_build()?;                          // or .build(), which cannot fail

add_operator accepts any name, but a built-in always wins, so an operator registered as if or var never runs. The Custom Operators guide covers try_add_operator, try_build and sharing an operator between engines through Arc.

with_constant_folding(false) suits tooling that walks the compiled tree and would be surprised by {"+": [1, 2]} collapsing to a literal 3. The one-shot trace entry points (TracedSession::eval_str, eval_into) and TracedSession::compile compile with folding off whatever this setting says; TracedSession::eval and eval_borrowed run the Logic you pass.

Family

Family names an operator family: Core, DateTime, ExtString, ExtArray, ExtObject, ExtControl, ErrorHandling, ExtMath, Tensor, Flagd. Every variant exists in every build.

impl Family {
    pub const ALL: &'static [Family];
    pub const fn name(self) -> &'static str;      // "ExtString", as OperatorInfo::family reports it
    pub const fn is_compiled(self) -> bool;       // whether the build has its Cargo feature
}

Logic

The compiled, reusable rule tree. Output of Engine::compile.

• Send + Sync: wrap in Arc to share across threads (or use Engine::compile_arc to do it in one step).
• Immutable after construction.

Any engine can evaluate any rule. On an engine other than the one that compiled it, the rule looks its custom operators up by name, and a rule whose constants were folded under different evaluation settings is compiled again for that engine (once per distinct setting), so folded constants follow the evaluating engine’s config. In 6.0 a rule will evaluate only on its own engine; compiled_on finds the places that rely on the lookup.

Facts

let rule = engine.compile(r#"{"if": [{"var": "user.vip"},
    {"map": [{"var": "cart"}, {"var": "price"}]}, []]}"#)?;
let facts = rule.facts();

facts.reads();               // [cart, user.vip]: `DataPath`s from the root
facts.has_computed_reads();  // false: no path is computed at runtime
facts.reads_complete();      // true: `reads()` is everything the rule can read
facts.reads_data();          // true
facts.operators();           // ["if", "map", "val"]: canonical names
facts.custom_operators();    // []
facts.is_deterministic();    // true: no `now`, no custom operator

DataPath is one path as segments: segments(), is_root(), covers(&other), and a Display that joins segments with dots. What each answer covers, and what it leaves out, is in Rule Analysis.

Session

Reusable evaluation handle that owns a bumpalo::Bump. The session never auto-resets: you decide when to release arena memory back to the start-of-chunk position. Construct via Engine::session().

let mut session = engine.session();
let result_str: String = session.eval_str(&compiled, data_json)?;
let result_owned: datalogic_rs::datavalue::OwnedDataValue =
    session.eval(&compiled, data)?;

// feature = "serde_json"
let value: serde_json::Value = session.eval_into(&compiled, &serde_data)?;

// Zero-copy borrowed result; lives until the next &mut self call.
let view: &datalogic_rs::DataValue<'_> = session.eval_borrowed(&compiled, data)?;

session.reset();                       // bound peak memory between batches
session.reset_with_capacity(64 * 1024);
let bytes = session.allocated_bytes();
let engine_ref: &Engine = session.engine();

Session::eval / eval_str / eval_into / eval_as accept any EvalInput<'_>. eval_borrowed returns a &'a DataValue<'a> that borrows from the session’s arena; the borrow checker ends it at the next &mut self call. With feature = "budget", eval_metered(&compiled, data, budget) returns a Metered<OwnedDataValue>.

Session is Send and not Sync: one per thread or task.

SharedSession

Session<'engine, E = &'engine Engine> has a type parameter for how it holds its engine. Engine::session() borrows it (Session<'_>, the default). SharedSession, an alias for Session<'static, Arc<Engine>>, holds an Arc<Engine> instead, so it is 'static + Send: you can store it in a struct, move it to another thread or hold it across an .await without borrowing the engine. Both forms have the same methods.

use std::sync::Arc;
use datalogic_rs::{Engine, SharedSession};

let engine = Arc::new(Engine::new());
let logic = engine.compile(r#"{"var": "x"}"#)?;
let mut session = SharedSession::new(Arc::clone(&engine)); // or SharedSession::from(engine)
let handle = std::thread::spawn(move || session.eval_str(&logic, r#"{"x": 1}"#));
assert_eq!(handle.join().unwrap()?, "1");

EvalInput

Sealed input adapter trait used by Engine::evaluate and the Session methods, and the OwnedInput cousin used by the owned one-shot entry points.

The trait is sealed; external crates cannot add new shapes.

On the engine that compiled a rule, an owned, serde_json or Roots input is brought in only along the paths the rule reads, when Logic::facts says those reads are complete. A rule with a computed path, a custom operator that may read the context, or a read of the whole input sees the whole input, as do traced runs and evaluation on another engine. JSON text and ParsedData are not projected.

Roots

Several values evaluated as the fields of one top-level object, without building that object. Each root is borrowed and viewed in place the way the engine views a single input of that type, so a host that keeps a payload and its metadata apart does not copy both into a combined value for every evaluation.

let roots = Roots::from([("data", &payload), ("metadata", &metadata)]);
session.eval_into::<serde_json::Value, _>(&compiled, &roots)?;

// Mixed representations, built up one root at a time:
let roots = Roots::new()
    .root("data", &payload)        // &serde_json::Value
    .root("claims", &claims)       // &OwnedDataValue
    .root("config", &parsed);      // &ParsedData

A rule reads {"var": "data.user"} exactly as it would from {"data": payload, "metadata": metadata}. Names keep the order they were first given in (the key order of {"var": ""}), and a repeated name replaces its value in place. Roots is accepted wherever the engine takes input, by reference or by value. Each root is a RootValue, built through From from &serde_json::Value, &OwnedDataValue, &ParsedData or &DataValue. insert(name, value), names(), len() and is_empty() complete the type.

Against a json!({"data": data, "metadata": metadata}) merge built per evaluation, Roots measured 7 to 10 times faster for payloads of 4 to 1,024 fields.

OwnedInput

The owned-entry-point cousin used by Engine::eval* and the module-level helpers, where the engine creates and owns the arena per call. Also sealed; the supported shapes are &str and &String (parsed into the per-call arena), &OwnedDataValue and OwnedDataValue (viewed in place), &serde_json::Value (feature = "serde_json", viewed in place), and &Roots / Roots.

FromDataValue

Sealed result-side counterpart: the R in Session::eval*, Engine::eval_as and TracedSession::eval* is projected out of the arena through FromDataValue::from_arena(&DataValue) -> Result<R>. Implemented for OwnedDataValue (deep clone), String (JSON serialisation), and serde_json::Value (feature = "serde_json"). The typed eval_into::<T> paths go through serde_json::Value and then serde_json::from_value.

ParsedData

A parse-once data handle: a self-contained JSON document that owns its own arena. Parse a payload once, then evaluate any number of rules against it at zero per-call conversion cost (&ParsedData implements EvalInput).

impl ParsedData {
    pub fn from_json(json: &str) -> Result<Self>;                 // ParseError on malformed input
    pub fn from_value(value: &serde_json::Value) -> Self;         // feature = "serde_json"
    pub fn from_owned(value: &OwnedDataValue) -> Self;
    pub fn value(&self) -> &DataValue<'_>;                        // borrow the parsed tree
    pub fn allocated_bytes(&self) -> usize;                       // input copy + tree
}

use datalogic_rs::{Engine, ParsedData};
use datalogic_rs::bumpalo::Bump;

let engine = Engine::new();
let data = ParsedData::from_json(r#"{"user": {"age": 34}}"#)?;

let adult = engine.compile(r#"{">=": [{"var": "user.age"}, 18]}"#)?;
let senior = engine.compile(r#"{">=": [{"var": "user.age"}, 65]}"#)?;

let arena = Bump::new();
assert_eq!(engine.evaluate(&adult, &data, &arena)?.as_bool(), Some(true));
assert_eq!(engine.evaluate(&senior, &data, &arena)?.as_bool(), Some(false));

ParsedData is Send (move it across threads) but not Sync; share by cloning the source string or parsing once per thread.

DataValue / OwnedDataValue

DataValue<'a> is the arena-resident value tree:

enum DataValue<'a> {
    Null,
    Bool(bool),
    Number(NumberValue),
    String(&'a str),
    Array(&'a [DataValue<'a>]),
    Object(&'a [(&'a str, DataValue<'a>)]),
    DateTime(...),  // feature = "datetime"
    Duration(...),  // feature = "datetime"
    Tensor(...),    // feature = "tensor"
}

Both DataValue and OwnedDataValue are re-exported from the datavalue crate. Use arena.alloc(...) to return values from custom operators; use OwnedDataValue when you need a heap-allocated owned tree (e.g. as the return of Engine::eval / Session::eval).

EvaluationConfig

Configuration for evaluation behavior. The struct is #[non_exhaustive], so you cannot build it with a struct literal from outside the crate. Construct it via default() (or a preset) and chain the with_* setters:

// #[non_exhaustive]: fields shown for reference, not for direct literals.
pub struct EvaluationConfig {
    pub arithmetic_nan_handling: NanHandling,        // default: ThrowError
    pub division_by_zero: DivisionByZeroHandling,    // default: ReturnSaturated
    pub loose_equality_errors: bool,                 // default: true
    pub truthy_evaluator: TruthyEvaluator,           // default: JavaScript
    pub numeric_coercion: NumericCoercionConfig,     // default: NumericCoercionConfig::default()
    pub max_recursion_depth: u32,                    // default: 256
    #[cfg(feature = "budget")]
    pub ops_budget: Option<u64>,                     // default: None (unbounded)
    pub missing_var: MissingVar,                     // default: Null
}

let config = EvaluationConfig::default()
    .with_arithmetic_nan_handling(NanHandling::ThrowError)
    .with_division_by_zero(DivisionByZeroHandling::ReturnSaturated)
    .with_loose_equality_errors(true)
    .with_truthy_evaluator(TruthyEvaluator::JavaScript)
    .with_numeric_coercion(NumericCoercionConfig::default())
    .with_max_recursion_depth(256)
    .with_missing_var(MissingVar::Null);

Presets:

EvaluationConfig::default();
EvaluationConfig::safe_arithmetic();
EvaluationConfig::strict();

With feature = "serde_json", EvaluationConfig::from_json_str builds one from the JSON object the bindings use. What each setting does is in the Configuration guide.

NanHandling

pub enum NanHandling {
    ThrowError,    // default
    IgnoreValue,
    CoerceToZero,
    ReturnNull,
}

DivisionByZeroHandling

pub enum DivisionByZeroHandling {
    ReturnSaturated,    // default: f64::MAX / MIN with the dividend's sign
    ThrowError,
    ReturnNull,
    ReturnInfinity,     // f64::INFINITY as a DataValue; null on the JSON-string paths
}

Applies to the float path only: an integer dividend over an integer zero ({"/": [10, 0]}) raises Thrown { type: "NaN" } under every setting, because no in-range integer sentinel exists. A fractional dividend ({"/": [10.5, 0]}) takes the configured path. See Division by Zero.

TruthyEvaluator

pub enum TruthyEvaluator {
    JavaScript,    // default
    Python,
    StrictBoolean,
    Custom(Arc<dyn Fn(&OwnedDataValue) -> bool + Send + Sync>),
}

The Custom callback receives an &OwnedDataValue, so it needs no serde_json. TruthyEvaluator::custom(f) wraps a closure without spelling out the Arc::new(...):

let config = EvaluationConfig::default().with_truthy_evaluator(
    TruthyEvaluator::custom(|v: &OwnedDataValue| {
        v.as_i64().map(|n| n % 2 == 0).unwrap_or(false)   // even integers are truthy
    }),
);

MissingVar

#[non_exhaustive]
pub enum MissingVar {
    Null,     // default: a `var` / `val` that finds nothing is null
    Error,    // raises VariableNotFound naming the path
}

See Missing Variables.

CustomOperator Trait

pub trait CustomOperator: Send + Sync {
    fn evaluate<'a>(
        &self,
        args: &[&'a DataValue<'a>],
        ctx: &mut operator::EvalContext<'_, 'a>,
        arena: &'a bumpalo::Bump,
    ) -> Result<&'a DataValue<'a>>;

    fn info(&self) -> CustomOperatorInfo { CustomOperatorInfo::opaque() }
    fn check(&self, args: &[OwnedDataValue]) -> std::result::Result<(), Diagnostic> { Ok(()) }
}

info declares what the engine may assume about the operator as a CustomOperatorInfo (fields deterministic, reads_context, min_args, max_args; built with opaque(), pure(), reading_context() and with_args(min, max)). check validates a call’s arguments as written for Engine::check. Box<dyn CustomOperator> and Arc<T: CustomOperator + ?Sized> implement the trait and forward all three methods. See Custom Operators.

ArenaExt

Extension trait on bumpalo::Bump (bring it into scope with use datalogic_rs::ArenaExt;) that folds “build a DataValue, then allocate it” into one call. It returns static singletons where it can (null, bool, small integers, empty strings/arrays/objects), which makes it the recommended way to return values from a custom operator.

pub trait ArenaExt<'a> {
    fn null(&'a self) -> &'a DataValue<'a>;
    fn bool(&'a self, b: bool) -> &'a DataValue<'a>;
    fn i64(&'a self, n: i64) -> &'a DataValue<'a>;
    fn f64(&'a self, n: f64) -> &'a DataValue<'a>;
    fn string(&'a self, s: &str) -> &'a DataValue<'a>;
    fn array(&'a self, items: &[DataValue<'a>]) -> &'a DataValue<'a>;
    fn object(&'a self, pairs: &[(&'a str, DataValue<'a>)]) -> &'a DataValue<'a>;
}

use datalogic_rs::{ArenaExt, CustomOperator, DataValue, Result};
use datalogic_rs::operator::EvalContext;

struct Triple;
impl CustomOperator for Triple {
    fn evaluate<'a>(
        &self,
        args: &[&'a DataValue<'a>],
        _ctx: &mut EvalContext<'_, 'a>,
        arena: &'a bumpalo::Bump,
    ) -> Result<&'a DataValue<'a>> {
        let n = args.first().and_then(|v| v.as_f64()).unwrap_or(0.0);
        Ok(arena.f64(n * 3.0))
    }
}

EvalContext

operator::EvalContext<'_, 'a> is an opaque view into the engine’s evaluation context, passed to CustomOperator::evaluate. Most custom operators don’t need it. It offers:

• root_input(): the input the evaluation started from;
• depth(): the number of iteration frames enclosing operators pushed;
• charge(n): charge n operations against the operation budget before doing work the node count does not reflect. Without the budget feature it returns Ok(()), so you can call it unconditionally.

The stack layout stays private so it can change without breaking the trait contract.

Rule analysis types

Rule Analysis covers these in full.

Error

Structured error type:

#[non_exhaustive]
pub struct Error {
    pub kind: ErrorKind,
    /* private fields: operator, node_ids */
}

// Read the contextual metadata via accessor methods, not fields:
impl Error {
    pub fn code(&self) -> ErrorCode;          // the kind without its payload
    pub fn tag(&self) -> &'static str;        // code().as_str()
    pub fn operator(&self) -> Option<&str>;   // innermost failing operator, when known
    pub fn node_ids(&self) -> &[u32];         // compiled-node breadcrumb, leaf-to-root
}

// ErrorKind variants carry `Cow<'static, str>` payloads (not `String`).
// The enum is #[non_exhaustive]: a `match` on `error.kind` needs a `_ =>` arm.
#[non_exhaustive]
pub enum ErrorKind {
    InvalidOperator(Cow<'static, str>),
    InvalidArguments(Cow<'static, str>),
    VariableNotFound(Cow<'static, str>),
    InvalidContextLevel(isize),
    TypeError(Cow<'static, str>),
    ArithmeticError(Cow<'static, str>),
    Custom(CustomErrorSource),
    ParseError(Cow<'static, str>),
    Thrown(OwnedDataValue),
    FormatError(Cow<'static, str>),
    IndexOutOfBounds { index: isize, length: usize },
    ConfigurationError(Cow<'static, str>),
    BudgetExceeded { budget: u64, spent: u64 },   // raised only with feature = "budget"
}

Error::operator() names the innermost operator on the failing path, custom operators included, on plain and traced runs alike; when no node on the path has an operator name, the rule’s root operator stands in.

ErrorKind::BudgetExceeded exists in every build, so a match on it compiles whatever features are on; only a budget build raises it.

Error implements serde::Serialize (in every build) as:

{
  "type": "<KindTag>",
  "message": "<Display>",
  "operator": "<name>",        // present only when known
  "node_ids": [42, 13, 7],     // present only when non-empty
  // kind-specific extras: variable, level, thrown, index/length, budget/spent
}

Use error.code() to switch on the kind, error.thrown_value() for the Thrown payload, and error.resolve_path(&compiled) to translate the node_ids breadcrumb into source PathSteps.

To wrap a foreign std::error::Error into a Custom error:

"abc".parse::<i32>().map_err(datalogic_rs::Error::wrap)?;

Error::source() walks the inner chain unchanged.

ErrorCode

ErrorCode is an error’s kind without its payload: one variant per ErrorKind variant, Copy, Eq, Hash and Ord, with every variant present in every build. as_str() (also its Display) is the name Error::tag() returns, which the bindings carry on the wire, and FromStr parses it back, failing with UnknownErrorCode. ErrorCode::ALL lists every code, and ErrorKind::code() gives the code of a bare kind. The enum is #[non_exhaustive].

use datalogic_rs::{Engine, ErrorCode};

let engine = Engine::new();
let err = engine.eval_str(r#"{"/": [1, 0]}"#, "{}").unwrap_err();
assert_eq!(err.code(), ErrorCode::Thrown);
assert_eq!("Thrown".parse::<ErrorCode>(), Ok(ErrorCode::Thrown));

Error Constructors

Error::new(kind)              // from an ErrorKind, no operator / node metadata
Error::invalid_operator(name)
Error::invalid_arguments(msg)
Error::variable_not_found(name)
Error::invalid_context_level(level)
Error::type_error(msg)
Error::arithmetic_error(msg)
Error::custom_message(msg)    // string-only
Error::wrap(err)              // any Error + Send + Sync + 'static
Error::parse_error(msg)
Error::thrown(value)
Error::format_error(msg)
Error::index_out_of_bounds(index, length)
Error::configuration_error(msg)

// Builder-style metadata (the engine sets these itself on errors that
// bubble out of an operator; only needed when constructing errors by hand):
error.with_operator(name)     // impl Into<Cow<'static, str>>
error.with_node_ids(ids)      // Vec<u32>, leaf-to-root

PathStep

Resolved entry returned by Logic::resolve_node_ids and Error::resolve_path, root to leaf. #[non_exhaustive], with Serialize / Deserialize:

pub struct PathStep {
    pub node_id: u32,              // matches Error::node_ids
    pub operator: Option<String>,  // None for plain values and arrays
    pub arg_index: Option<u32>,    // position in the parent's arguments; None at the root
    pub json_pointer: String,      // e.g. "/if/0/>/0"; "" for the root
}

json_pointer escapes tokens as RFC 6901 does (/ is ~1). For a rule compiled with TracedSession::compile it is Logic::pointer, the pointer into the rule as written.

Result Type

pub type Result<T> = std::result::Result<T, Error>;

Trace API (feature = “trace”)

TracedSession

Open via engine.trace(). Every eval* returns a TracedRun<R> with the same R that Session would return, but the inputs differ from Session: the one-shot methods take a rule source rather than a compiled &Logic, and there is no session-owned arena. TracedSession holds only a reference to the engine; each owned call allocates a fresh Bump, and eval_borrowed uses the caller’s.

impl TracedSession<'_> {
    // Compile in this mode instead of the engine's (CheckMode::Strict / Template).
    pub fn with_mode(self, mode: CheckMode) -> Self;

    // Compile as the one-shot paths do (folding off) and record each node's JSON Pointer.
    pub fn compile<R: IntoLogic>(&self, rule: R) -> Result<Logic>;

    // Pre-compiled Logic + owned input; fresh per-call arena.
    pub fn eval<D: OwnedInput>(&self, compiled: &Logic, data: D) -> TracedRun<OwnedDataValue>;

    // Rule source (IntoLogic) + owned input; compiles with folding disabled.
    pub fn eval_str<R: IntoLogic, D: OwnedInput>(&self, rule: R, data: D) -> TracedRun<String>;
    #[cfg(feature = "serde_json")]
    pub fn eval_into<T: DeserializeOwned, R: IntoLogic, D: OwnedInput>(&self, rule: R, data: D) -> TracedRun<T>;

    // Pre-compiled Logic + arena input + caller-owned arena; borrowed result.
    pub fn eval_borrowed<'a, D: EvalInput<'a>>(
        &self,
        compiled: &'a Logic,
        data: D,
        arena: &'a bumpalo::Bump,
    ) -> TracedRun<&'a DataValue<'a>>;
}

// Cargo.toml: datalogic-rs = { version = "5", features = ["trace"] }
let engine = datalogic_rs::Engine::new();
let run = engine.trace().eval_str(r#"{"+": [1, 2]}"#, r#"{}"#);
println!("{}", run.result.unwrap());   // 3
println!("{} steps", run.steps.len());

The pre-compiled paths (eval, eval_borrowed) inherit whatever shape the Logic was compiled into: a rule from Engine::compile has its constant subexpressions folded, so those operators record no step. For full coverage, use eval_str / eval_into, or compile with engine.trace().compile(rule) and evaluate that Logic as many times as you need. A rule compiled that way also records, for every node id, the JSON Pointer of the rule value it came from: logic.pointer(step.node_id) places each ExecutionStep and ExpressionNode in the rule as written.

let engine = datalogic_rs::Engine::new();
let logic = engine.trace().compile(r#"{"if": [{"var": "a"}, 1, 2]}"#)?;
let run = engine.trace().eval(&logic, r#"{"a": true}"#);
assert_eq!(logic.pointer(run.steps[0].node_id), Some("/if/0"));

TracedRun<R> (feature = “trace”)

pub struct TracedRun<R> {
    pub result: Result<R, Error>,        // success and failure share one field
    pub steps: Vec<ExecutionStep>,
    pub expression_tree: ExpressionNode,
}

R is the same shape that Session::eval* would return: OwnedDataValue for eval, String for eval_str, T for eval_into::<T>, &'a DataValue<'a> for eval_borrowed.

pub struct ExecutionStep {
    pub step_id: u32,                  // recording order
    pub node_id: u32,                  // which compiled node ran
    pub context: serde_json::Value,    // scope data at this step
    pub result: Option<serde_json::Value>,
    pub error: Option<String>,
    pub iteration_index: Option<u32>,  // iterator bodies only
    pub iteration_total: Option<u32>,
}

pub struct ExpressionNode {
    pub id: u32,                       // matches ExecutionStep::node_id
    pub expression: String,            // JSON text of this sub-expression
    pub children: Vec<ExpressionNode>,
}

Steps carry no timing data; they record which nodes ran, in what order, and with what context and result.

Full Example

use datalogic_rs::{Engine, EvaluationConfig, NanHandling};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::builder()
        .with_config(
            EvaluationConfig::default()
                .with_arithmetic_nan_handling(NanHandling::IgnoreValue),
        )
        .build();

    let compiled = engine.compile_arc(
        r#"{"if": [{">=": [{"var": "score"}, 60]}, "pass", "fail"]}"#,
    )?;

    let mut session = engine.session();
    for score in [85, 45, 60] {
        let r = session.eval_str(&compiled, &format!(r#"{{"score": {}}}"#, score))?;
        println!("{} -> {}", score, r);
        session.reset();
    }

    Ok(())
}

See Also

• Rust Quick Start — evaluation tiers, input routes, and Cargo feature flags
• Configuration — EvaluationConfig and EngineBuilder options
• Custom Operators — implementing CustomOperator and ArenaExt
• Rule Analysis — Engine::check, compile_checked, Logic::facts, and Engine::operators
• Thread Safety — sharing Engine and Logic across threads and async tasks

Node.js (Native Binding)

@goplasmatic/datalogic-node is the native Node.js binding: the Rust core compiled per platform and loaded through napi-rs, with no WebAssembly in between. On Node servers it is the fast path.

Two npm packages, one engine. This package is for Node services that want maximum throughput. @goplasmatic/datalogic-wasm is the WebAssembly build: it also runs under Node, but its home turf is browsers, edge runtimes, Deno, and Bun. Both run the same core and pass the same conformance battery.

Install

npm install @goplasmatic/datalogic-node

The prebuilt platform binaries ship as optionalDependencies, so npm pulls only the .node file matching your platform:

Requires Node 18 or newer. There is no build step and no WASM initialization: import and call.

If require('@goplasmatic/datalogic-node') or import fails with MODULE_NOT_FOUND, upgrade to 5.8.0 or newer (5.9.0 is current). Versions 5.1.1 through 5.7.1 were published without the umbrella package’s index.js loader and index.d.ts typings, although the per-platform packages were complete.

Quick start

Rules and data are plain JavaScript objects; results come back as JavaScript values:

import { apply } from '@goplasmatic/datalogic-node';

const result = apply(
  { if: [{ '>': [{ var: 'score' }, 50] }, 'pass', 'fail'] },
  { score: 75 }
);
// -> "pass"

Both arguments also accept JSON text: the binding parses a JS string passed as rule or data as JSON instead of treating it as a string value. To evaluate against a data document that is a JSON string, pass it encoded (rule.evaluate(JSON.stringify('hello'))), or hand the JSON text to the string-in methods (evaluateStr) or a DataHandle.

An object that crosses the boundary as a JS value, in either direction, comes back with its keys sorted. To keep key order, pass JSON text and call a string-out method (evalStr, evaluateStr, evaluateDataStr).

Compile once, evaluate many

For repeated evaluations of the same rule, compile once and hold the Rule instance:

import { Engine } from '@goplasmatic/datalogic-node';

const engine = new Engine();
const rule = engine.compile({ '+': [{ var: 'x' }, 1] });

for (const payload of inputs) {
  console.log(rule.evaluate(payload));
}

Rule has no thread affinity on the Rust side, but napi class instances cannot be posted or transferred between worker_threads: a Rule sent through postMessage arrives as an empty plain object with no evaluate. Each worker must load the module and compile its own Rule (compiling is cheap). For parallelism from a single thread, rule.evaluateStrAsync(json) evaluates on the libuv pool (see Async evaluation).

The constructor takes an options bag and, separately, a map of custom operators:

const strict = new Engine({ config: { preset: 'strict' } });
const templated = new Engine({ templating: true });
const stringsOnly = new Engine({ families: ['ExtString'] });
const custom = new Engine({ strictOperatorNames: true }, {
  double: (argsJson) => String(JSON.parse(argsJson)[0] * 2),
});
custom.compile({ double: [21] }).evaluate({}); // 42

preset and the other evaluation options nest under config, not at the top level. The options bag reads only templating, templateKeyEscape, config, strictOperatorNames and families; it ignores other top-level keys, so new Engine({ preset: 'strict' }) builds a default engine.

• templateKeyEscape is a single-character prefix, unset by default, that lets a template emit a key which would otherwise run as an operator: with new Engine({ templating: true, templateKeyEscape: '$' }), { $type: { var: 'x' } } yields { type: 1 } rather than running the type operator, and { $$type: 1 } yields { $type: 1 }. Anything other than a one-character string throws errorType: 'InvalidArguments'. See Structured Objects.
• families keeps the engine to the JSONLogic core plus the operator families you name ('DateTime', 'ExtString', 'ExtArray', 'ExtObject', 'ExtControl', 'ErrorHandling', 'ExtMath', 'Tensor', 'Flagd'). Unset, the engine has every family. A family left out compiles its names as unknown operators, and a custom operator may take them.
• strictOperatorNames: true makes a custom operator named like a built-in (length, var, an alias such as ?:) throw at construction instead of registering one that never runs.

Unknown keys inside config, an unknown family name and a refused operator name throw errorType: 'ConfigurationError'. Configuration covers what each config option means, including missing_var: 'error', which makes a read of a missing variable throw VariableNotFound instead of returning null.

Templating mode per compile

engine.compileTemplate(rule) compiles in templating mode and engine.compileStrict(rule) outside it, whatever the engine was built with. Both use the engine’s custom operators and config, so one engine can check a condition strictly and build an output template:

engine.compileTemplate({ name: { var: 'user' }, active: true }).evaluate({ user: 'Alice' });
// { active: true, name: 'Alice' }

Checking a rule before it runs

compile rejects malformed JSON and structurally invalid rules (a multi-key object when templating is off), but it does not verify operator names: an unknown operator compiles and throws errorType: 'InvalidOperator' when you evaluate the rule. engine.check(rule, mode?) reports every problem the engine can see before the rule runs, each with a JSON Pointer into the rule; mode is 'engine' (the default), 'strict' or 'template':

engine.check({ if: [true, { vr: 'x' }, { map: [1] }] });
// [
//   { code: 'UnknownOperator', severity: 'error', pointer: '/if/1', operator: 'vr',
//     message: 'unknown operator `vr`; did you mean `var`?' },
//   { code: 'ArgumentCount', severity: 'error', pointer: '/if/2', operator: 'map',
//     message: '`map` takes exactly 2 arguments, not 1' }
// ]

An 'error' will fail; a 'warning' runs but is probably a mistake. engine.compileChecked(rule) compiles only a rule with no error diagnostic and otherwise throws an Error named CompileError whose diagnostics holds the same objects. Rule Analysis covers the diagnostic codes and check modes.

Sessions: hot-loop arena reuse

A Session reuses one bump arena across evaluations and resets between calls to bound peak memory. Open one per worker thread:

const sess = engine.session();
for (const payload of inputs) {
  sess.evaluate(rule, payload);
}

Sessions hold non-Sync state and must not be shared between worker threads.

Data handles and typed results

A DataHandle is an immutable, pre-parsed JSON document. Parse a payload once and every evaluation against it skips JSON parsing; the typed session methods also skip the result round trip:

import { DataHandle } from '@goplasmatic/datalogic-node';

const handle = new DataHandle('{"age": 25, "status": "active"}'); // throws ParseError on bad JSON
const isAdult = engine.compile({ '>=': [{ var: 'age' }, 18] });
const nextAge = engine.compile({ '+': [{ var: 'age' }, 1] });

nextAge.evaluateData(handle);         // 26   (JS value out, no parse per call)
nextAge.evaluateDataStr(handle);      // "26" (JSON string out)
sess.evaluateData(isAdult, handle);   // true (hot path: session arena + no parse)
sess.evaluateBool(isAdult, handle);   // true (strict JSON boolean, else TypeMismatch)
sess.evaluateInt(nextAge, handle);    // 26   (a whole number a JS number holds exactly, else TypeMismatch)
sess.evaluateFloat(nextAge, handle);  // 26   (any JSON number, else TypeMismatch)
sess.evaluateTruthy(isAdult, handle); // true (JSONLogic truthiness, never mismatches)

evaluateBool, evaluateInt and evaluateFloat throw an EvaluateError with errorType: 'TypeMismatch' when the rule evaluated fine but the result has another type. evaluateNumber is the deprecated name of evaluateFloat and is removed in 6.0. Handles are per-thread like sessions: parse one per worker.

Batch evaluation

The batch entry points evaluate a whole set in one native call and report outcomes per item in the Promise.allSettled shape, so one bad input never poisons its neighbours:

const outcomes = sess.evaluateBatch(rule, [h0, h1, h2]); // one rule, many payloads
const flags = sess.evaluateMany([r0, r1], handle);        // many rules, one payload

for (const [i, o] of flags.entries()) {
  if (o.status === 'rejected') {
    console.log(`rule ${i} failed: ${o.reason.message} (${o.reason.tag})`);
  } else {
    console.log(`rule ${i}: ${o.value}`); // result as a JSON string
  }
}

Async evaluation

rule.evaluateStrAsync(dataJson) evaluates on the libuv thread pool and returns a Promise<string>. It is no faster per call than evaluateStr; it keeps large payloads’ parse + evaluate + serialize off the event loop:

const result = await rule.evaluateStrAsync('{"age": 25}');

String input only (a DataHandle is pinned to the JS thread). Rejections carry the same structured fields as synchronous throws.

Tracing

engine.evaluateWithTrace(logic, data, mode?) takes JSON strings and returns a JSON string with the same { result, expression_tree, steps, pointers, error?, structured_error? } envelope the WASM package produces, so the React debugger accepts output from either package:

const run = JSON.parse(engine.evaluateWithTrace('{"+": [1, 2, 3]}', 'null'));
run.result;       // 6
run.steps.length; // 1 (one step per operator node; literals record no step)
run.pointers;     // { "1": "/+/0", "2": "/+/1", "3": "/+/2", "4": "" }

pointers maps each node id to the JSON Pointer of the rule value it was compiled from, so a debugger places each step in the rule as written. mode is 'engine' (the default), 'strict' or 'template', so a rule you compile with compileTemplate can be traced as one. Failures do not throw: result is null, error carries the message, and structured_error the structured form. The binding compiles the rule with optimization disabled so every operator surfaces a step; use it for debugging, not hot paths.

Operator names

Tooling that validates or autocompletes rules can ask the binding for its vocabulary instead of keeping a hand-maintained list:

import { builtinOperatorNames, Engine } from '@goplasmatic/datalogic-node';

const names = builtinOperatorNames();
names.length;               // 87: the 84 built-in operators plus the aliases var, ?:, match
names.includes('group_by'); // true

const engine = new Engine({}, { double: (a) => String(JSON.parse(a)[0] * 2) });
engine.customOperatorNames(); // ['double']

builtinOperatorNames() is derived from the compiler’s own lookup table, so it cannot drift from dispatch; engine.customOperatorNames() lists the operators registered on that engine. For an engine with every operator family, the union is the engine’s full vocabulary; engine.operators() follows an engine’s families.

Three more calls describe the engine and a rule without running anything:

engine.operators().find((op) => op.name === 'reduce');
// { name: 'reduce', aliases: [], family: 'Core', feature: null, min_args: 2, max_args: 3,
//   reads_context: false, effect: 'pure', cost: 'per_item', scoped_arg: 1 }

engine.compile({ '+': [{ var: 'a.b' }, { var: 'c' }] }).facts();
// { reads: [['a', 'b'], ['c']], computed_reads: false, reads_complete: true,
//   reads_data: true, operators: ['+', 'val'], custom_operators: [], deterministic: true }

engine.truthy({});   // false: an empty object is falsy, like an empty array
engine.truthy('[]'); // false: a string is JSON text

operators() is the operator catalogue: one row per built-in operator the engine evaluates, following its families. facts() lists the data paths a compiled rule reads (as segment lists) and the operators it calls; reads_complete is false when a path is computed at runtime or a custom operator runs, and deterministic is false for now and any custom operator. truthy() applies the engine’s configured truthiness.

Error handling

Failures throw plain JS Error instances with structured fields attached:

try {
  rule.evaluate(data);
} catch (e) {
  if (e.name === 'ParseError') {
    // Malformed rule or data JSON
  } else if (e.name === 'EvaluateError') {
    console.log(e.errorType);  // stable tag (e.g. "InvalidOperator", "Thrown")
    console.log(e.operator);   // innermost failing operator
    console.log(e.nodeIds);    // leaf-to-root breadcrumb
    console.log(e.path);       // resolved root-to-leaf step list
  }
}

e.name is 'ParseError', 'EvaluateError', 'CompileError' (from compileChecked, with a diagnostics array) or 'InternalError'. An InternalError is a panic inside the native engine, caught at the binding boundary and thrown (or, for evaluateStrAsync, rejected) instead of aborting the process; the engine, rule and session stay usable, and it always means a bug worth reporting. A BudgetExceeded error carries budget and spent.

Missing data is not an error by default: { var: 'missing' } evaluates to null. An engine built with config: { missing_var: 'error' } throws errorType: 'VariableNotFound' instead.

API surface

The package README carries the same surface with the configuration key table; Configuration covers what each option means.

When to choose WASM instead

Choose @goplasmatic/datalogic-wasm when the code must run in a browser or edge runtime, or when you want one artifact across Node + browser. Choose this native package for Node services where throughput matters: the WASM build measures roughly 88× slower than the native core on the same benchmark workload.

Next steps

• Integration: Express for the compile-once, cache-by-version service pattern
• Starter Boilerplates for a minimal Express authorization middleware
• Framework integration patterns for React, Vue, and worker recipes (applicable to both JS packages)
• Operation Budget and Security & Sandboxing for running untrusted rules safely
• Use cases & examples and Thread safety

Installation

Two npm packages, one engine. This chapter covers @goplasmatic/datalogic-wasm, the WASM build: pick it for browsers, edge runtimes, Deno, and anywhere portability matters. For Node.js servers, prefer the native @goplasmatic/datalogic-node package (napi), which calls the Rust core without a WebAssembly layer.

The @goplasmatic/datalogic-wasm package provides WebAssembly bindings for the datalogic-rs engine, so you can evaluate JSONLogic from JavaScript and TypeScript.

Package Installation

# npm
npm install @goplasmatic/datalogic-wasm

# yarn
yarn add @goplasmatic/datalogic-wasm

# pnpm
pnpm add @goplasmatic/datalogic-wasm

The package declares Node 18 or newer (engines.node) for the Node.js target.

Build Targets

The package includes three build targets, one per environment:

Automatic Target Selection

The package’s exports field selects a target by export condition:

// Browser/Bundler - the `import` condition resolves to the web target
import init, { Engine } from '@goplasmatic/datalogic-wasm';

// Node.js - the `node` condition resolves to the nodejs target
const { Engine } = require('@goplasmatic/datalogic-wasm');

Explicit Target Import

If you need a specific target:

// Web target (ES modules with init)
import init, { Engine } from '@goplasmatic/datalogic-wasm/web';

// Bundler target (no init; the module instantiates on import)
import { Engine } from '@goplasmatic/datalogic-wasm/bundler';

// Node.js target
import { Engine } from '@goplasmatic/datalogic-wasm/nodejs';

The bundler target imports datalogic_wasm_bg.wasm as an ES module, so it needs Webpack’s experiments.asyncWebAssembly (or the equivalent in your bundler); see Bundler Configuration.

WASM Initialization

For browser and bundler environments, initialize the WASM module before you use any export:

import init, { Engine } from '@goplasmatic/datalogic-wasm';

// Initialize once at application startup
await init();

// Then build an engine and evaluate
const engine = new Engine();
const result = engine.evalStr('{"==": [1, 1]}', '{}'); // "true"

On Node.js, use the exports right after import, with no initialization. Do not call init() there: with the bare specifier, Node resolves to the CommonJS nodejs target, so a default import binds init to the module namespace object and await init() throws TypeError: init is not a function. Code that has to run in both places should guard the call:

import init, { Engine } from '@goplasmatic/datalogic-wasm';
if (typeof init === 'function') await init(); // browser: loads the module; Node: no-op

Or import from @goplasmatic/datalogic-wasm/nodejs and skip init.

TypeScript Support

The package includes TypeScript declarations. No additional @types package is needed.

import init, { Engine, Rule } from '@goplasmatic/datalogic-wasm';

await init();
const engine = new Engine();
const rule: Rule = engine.compile('{"==": [1, 1]}');
const result: string = rule.evaluate('{}'); // "true"

The declarations mark the deprecated exports (evaluate, evaluateWithTrace, CompiledRule, Session.evaluateNumber) with @deprecated, so your editor flags them; see Deprecated APIs.

Bundle Size

The WASM binary is a single self-contained module: about 5.2 MB uncompressed and about 1.0 MB gzipped in the 5.9.0 release build. It compiles in the IANA timezone database used by the datetime feature’s format_date and parse_date timezone arguments. Size-sensitive embedders building from source can shrink it by setting CHRONO_TZ_TIMEZONE_FILTER to only the zones they need; see Building from source.

CDN Usage

For prototypes or simple pages, you can load the module from a CDN:

<script type="module">
  import init, { Engine } from 'https://unpkg.com/@goplasmatic/datalogic-wasm@latest/web/datalogic_wasm.js';

  async function run() {
    await init();
    const engine = new Engine();
    console.log(engine.evalStr('{"==": [1, 1]}', '{}')); // "true"
  }

  run();
</script>

Next Steps

• Quick Start - Basic usage examples
• API Reference - Functions, classes, configuration, and error shapes
• Framework Integration - React, Vue, and bundler setup

Quick Start

The core patterns for using JSONLogic from JavaScript/TypeScript.

Basic Evaluation

Build an Engine once, then evaluate:

import init, { Engine } from '@goplasmatic/datalogic-wasm';

// Initialize WASM (browser/bundler only; on Node the default import is not
// a function, so guard the call or import from '@goplasmatic/datalogic-wasm/nodejs')
if (typeof init === 'function') await init();

const engine = new Engine();

// Evaluate a simple expression
const result = engine.evalStr('{"==": [1, 1]}', '{}');
console.log(result); // "true"

Working with Data

Pass data as a JSON string for variable resolution:

// Access nested data
const logic = '{"var": "user.age"}';
const data = '{"user": {"age": 25}}';
const result = engine.evalStr(logic, data);
console.log(result); // "25"

// Multiple variables
const priceLogic = '{"*": [{"var": "price"}, {"var": "quantity"}]}';
const orderData = '{"price": 10.99, "quantity": 3}';
console.log(engine.evalStr(priceLogic, orderData)); // "32.97"

Compiled Rules

For repeated evaluation of the same logic, compile it once with engine.compile instead of passing it to evalStr on every call:

import init, { Engine } from '@goplasmatic/datalogic-wasm';

if (typeof init === 'function') await init();

const engine = new Engine();

// Compile once
const rule = engine.compile('{">=": [{"var": "age"}, 18]}');

// Evaluate many times with different data
console.log(rule.evaluate('{"age": 21}')); // "true"
console.log(rule.evaluate('{"age": 16}')); // "false"
console.log(rule.evaluate('{"age": 18}')); // "true"

Parsing Results

Every call returns its result as a JSON string. Parse it for use in your application:

const result = engine.evalStr('{"+": [1, 2, 3]}', '{}');
const value = JSON.parse(result); // 6 (number)

// For complex results
const arrayResult = engine.evalStr('{"map": [[1,2,3], {"+": [{"var": ""}, 10]}]}', '{}');
const array = JSON.parse(arrayResult); // [11, 12, 13]

Conditional Logic

Use if for branching:

const gradeLogic = JSON.stringify({
  "if": [
    { ">=": [{ "var": "score" }, 90] }, "A",
    { ">=": [{ "var": "score" }, 80] }, "B",
    { ">=": [{ "var": "score" }, 70] }, "C",
    { ">=": [{ "var": "score" }, 60] }, "D",
    "F"
  ]
});

const rule = engine.compile(gradeLogic);
console.log(JSON.parse(rule.evaluate('{"score": 85}'))); // "B"
console.log(JSON.parse(rule.evaluate('{"score": 42}'))); // "F"

Array Operations

Process arrays with map, filter, and reduce:

// Filter items
const filterLogic = JSON.stringify({
  "filter": [
    { "var": "items" },
    { ">": [{ "var": "price" }, 20] }
  ]
});

const data = JSON.stringify({
  items: [
    { name: "Book", price: 15 },
    { name: "Phone", price: 299 },
    { name: "Pen", price: 5 },
    { name: "Headphones", price: 50 }
  ]
});

const result = JSON.parse(engine.evalStr(filterLogic, data));
// [{ name: "Phone", price: 299 }, { name: "Headphones", price: 50 }]

Templating Mode

Compile a multi-key object with compileTemplate to use it as a JSON template:

const template = JSON.stringify({
  "user": {
    "fullName": { "cat": [{ "var": "firstName" }, " ", { "var": "lastName" }] },
    "isAdult": { ">=": [{ "var": "age" }, 18] }
  },
  "timestamp": { "now": [] }
});

const data = JSON.stringify({
  firstName: "Alice",
  lastName: "Smith",
  age: 25
});

// compileTemplate: multi-key objects become output templates for this rule
const result = JSON.parse(engine.compileTemplate(template).evaluate(data));
// {
//   "user": { "fullName": "Alice Smith", "isAdult": true },
//   "timestamp": "2024-01-15T10:30:00Z"   (the current time, ISO 8601 UTC)
// }

To make templating the default for every compile, build the engine with new Engine({ templating: true }).

Error Handling

Wrap evaluations in try-catch. Failures throw a real Error whose name is a stable tag ("ParseError", "InvalidOperator", "Thrown", …); see Error Handling for the full shape:

try {
  const result = engine.evalStr('{"invalid": "json', '{}');
} catch (error) {
  console.error('Evaluation failed:', error.name, error.message);
  // Evaluation failed: ParseError Parse error: json parse error at byte 17: unexpected end of input
}

To catch mistakes such as a misspelled operator before a rule runs, compile it with engine.compileChecked(logic), which throws a CompileError listing every problem, or call engine.check(logic) for the list itself; see check.

Debugging

Use engine.evaluateWithTrace for step-by-step debugging:

import init, { Engine } from '@goplasmatic/datalogic-wasm';

if (typeof init === 'function') await init();

const engine = new Engine();
const trace = engine.evaluateWithTrace(
  '{"and": [{"var": "a"}, {"var": "b"}]}',
  '{"a": true, "b": false}'
);

const traceData = JSON.parse(trace);
console.log('Result:', traceData.result);      // Result: false
console.log('Steps:', traceData.steps.length); // Steps: 3 (var a, var b, and)

Each step records the node id, the data context it saw, and its result (or error). Literal operands do not record steps.

Next Steps

• Installation - Build targets (web, bundler, nodejs) and WASM initialization
• API Reference - Complete class, method, configuration, and error documentation
• Framework Integration - React, Vue, Next.js, and bundler setup
• Node.js Native Binding - Faster native N-API binding for Node.js servers
• React Visual Debugger - Ready-made React rule editor and step-through debugger

API Reference

API documentation for the @goplasmatic/datalogic-wasm WebAssembly package.

The package exports the builtinOperatorNames function, four classes (Engine, Rule, Session, DataHandle), and, on the web target only, the default-exported init loader and initSync. It also still exports the deprecated evaluate and evaluateWithTrace functions and the CompiledRule class; see Deprecated APIs. Rules, data and results cross the boundary as JSON strings, except where a method below says otherwise; see Input/Output Types.

Functions

init()

Initialize the WebAssembly module. Required before using any other export in browser/bundler environments (the web target). It is the module’s default export.

type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;

function init(options?: { module_or_path: InitInput | Promise<InitInput> }): Promise<InitOutput>;

Parameters:

• options.module_or_path (optional) - Custom WASM source (URL, Response, BufferSource, or a compiled WebAssembly.Module). Defaults to datalogic_wasm_bg.wasm next to the JS glue.

Returns: Promise that resolves when initialization is complete

Example:

import init from '@goplasmatic/datalogic-wasm';

// Standard initialization
await init();

// Custom WASM location
await init({ module_or_path: '/custom/path/datalogic_wasm_bg.wasm' });

Passing the source positionally (init('/path/to.wasm')) still works, but wasm-bindgen deprecates it and logs a console warning; use the object form. The web target also exports initSync({ module }), which instantiates synchronously from bytes or a compiled WebAssembly.Module you already hold (in a Worker, for example).

Node.js does not require initialization, and init is not a function there. The package’s node export condition resolves the bare specifier to the CommonJS nodejs target, so a default import (import init from '@goplasmatic/datalogic-wasm') binds init to the module namespace object and await init() throws TypeError: init is not a function. Code that has to run in both places should guard the call:

import init, { Engine } from '@goplasmatic/datalogic-wasm';
if (typeof init === 'function') await init(); // no-op on Node

Or import the Node target (@goplasmatic/datalogic-wasm/nodejs) and skip init.

builtinOperatorNames()

Every built-in operator name this WASM build accepts, in the engine’s registry order.

function builtinOperatorNames(): string[];

Returns: Array of operator keys. The list includes the input aliases (var for val, ?: for if, match for switch), so it has 87 entries for the 84 built-in operators. It is derived from the compiler’s own lookup table, so tooling (editors, linters, palettes) can validate rules against the engine instead of a hand-maintained list. The list excludes custom operators (see engine.customOperatorNames()) and lists every family whatever an engine’s families option says; engine.operators() follows the engine.

Example:

import { builtinOperatorNames } from '@goplasmatic/datalogic-wasm';

const names = builtinOperatorNames();
names.length;                  // 87
names.includes('group_by');    // true
names.includes('var');         // true (alias of val)
names.includes('preserve');    // false (removed in v5)

Classes

Engine

A configurable engine: templating mode, an evaluation config, operator families, and custom operators. It compiles rules into Rule objects and opens Sessions.

Constructor

new Engine(options?: {
  templating?: boolean;
  templateKeyEscape?: string;
  customOperators?: Record<string, (argsJson: string) => string>;
  config?: string | object;
  strictOperatorNames?: boolean;
  families?: string[];
})

Parameters:

• templating - Make templating mode the default for every rule this engine compiles (multi-key objects compile to output-shaping templates). compileTemplate / compileStrict choose per rule.
• templateKeyEscape - Single-character prefix that marks a template key as a literal output field rather than an operator invocation. Unset by default. With '$', {"$type": ...} emits the key type instead of running the type operator, and {"$$type": ...} emits a literal $type. Only meaningful in templating mode; anything other than a one-character string throws. See Structured Objects
• customOperators - Map of operator name to callback. Each callback receives the pre-evaluated arguments as a JSON-array string and must return a JSON-value string (null/undefined count as JSON null). A thrown exception or a non-string return becomes a runtime evaluation error. Built-ins win: registering a built-in name (+, if, var, …) has no effect.
• config - Evaluation config; see Engine configuration
• strictOperatorNames - When true, a custom operator named like a built-in (aliases included) throws a ConfigurationError instead of being registered and never running. Defaults to false.
• families - The operator families the engine has besides the JSONLogic core: "DateTime", "ExtString", "ExtArray", "ExtObject", "ExtControl", "ErrorHandling", "ExtMath", "Tensor", "Flagd" (the family of each operators() row). Unset, the engine has every family. A family left out is not there for this engine: its names compile as unknown operators (failing at evaluation with InvalidOperator, and errors in check), count as output fields in templating mode, and are free for a custom operator.

Throws: ConfigurationError for an unknown config key or value, an unknown family name, or a built-in name under strictOperatorNames; ParseError (stage: "parse-options") for a malformed options bag.

Example:

import init, { Engine } from '@goplasmatic/datalogic-wasm';
await init();

const engine = new Engine({
  customOperators: {
    double: (argsJson) => String(JSON.parse(argsJson)[0] * 2),
  },
});
engine.evalStr('{"double": [21]}', '{}'); // "42"

const stringsOnly = new Engine({ families: ['ExtString'] });
stringsOnly.evalStr('{"upper": ["a"]}', '{}'); // '"A"'
stringsOnly.evalStr('{"now": []}', '{}');      // throws Error { name: "InvalidOperator", operator: "now" }

Methods

compile(logic: string): Rule

Compile a rule against this engine (its config and custom operators apply), in the engine’s templating mode.

Throws: ParseError for malformed JSON; InvalidOperator for a multi-key object outside templating mode. compile does not reject unknown operator names: they surface as an InvalidOperator error when you evaluate the rule. Use compileChecked to refuse them up front.

const rule = engine.compile('{">=": [{"var": "age"}, 18]}');
rule.evaluate('{"age": 21}'); // "true"

compileTemplate(logic: string): Rule

Compile logic in templating mode, whatever this engine was built with: a multi-key object is an output template and an unknown key an output field.

const engine = new Engine();
engine.compileTemplate('{"name": {"var": "user"}, "active": true}').evaluate('{"user": "Alice"}');
// '{"name":"Alice","active":true}'

compileStrict(logic: string): Rule

Compile logic outside templating mode, whatever this engine was built with: a multi-key object is an error.

compileChecked(logic: string): Rule

Compile logic in the engine’s mode only if check finds no error diagnostic.

Throws: an Error named CompileError whose diagnostics property holds every problem (the same objects check returns).

try {
  engine.compileChecked('{"if": [{"bogus": 1}, {"map": [1]}]}');
} catch (e) {
  e.name;                                  // "CompileError"
  e.diagnostics.map((d) => d.pointer);     // ["/if/0", "/if/1"]
}

check(logic: string, mode?: string): string

Every problem the engine can see in logic before it runs, in one pass, as a JSON array of diagnostics. mode is "engine" (the default: the engine’s own templating mode), "strict" or "template"; any other value throws a ParseError.

interface Diagnostic {
  code: string;               // "UnknownOperator", "NotAnOperator", "ArgumentForm", "ArgumentCount",
                              // "InvalidTimezone", "SimilarToOperator", "Unparsable", "Compile", ...
  severity: 'error' | 'warning';
  message: string;            // names the operator involved
  pointer: string;            // RFC 6901 JSON Pointer into the rule; "" is the whole rule
  operator: string | null;
}

Errors are what will fail: an object with several keys outside templating mode, an unknown operator (with a “did you mean” suggestion one edit away), and / or / if without an argument array, an argument count the operator rejects, a literal timezone that does not exist. Warnings run but are probably mistakes: arguments an operator never evaluates, and in a template an output key one edit away from an operator name. Malformed JSON is an Unparsable diagnostic, not a throw.

JSON.parse(engine.check('{"if": [true, {"vr": "x"}, {"map": [1]}]}'));
// [
//   { code: "UnknownOperator", severity: "error", message: "unknown operator `vr`; did you mean `var`?",
//     pointer: "/if/1", operator: "vr" },
//   { code: "ArgumentCount", severity: "error", message: "`map` takes exactly 2 arguments, not 1",
//     pointer: "/if/2", operator: "map" }
// ]

engine.check('{"a": {"var": "x"}, "b": 1}', 'template'); // "[]"

Rule Analysis covers the diagnostics, check modes, rule facts and the operator catalogue across the engine and every binding.

evalStr(logic: string, data: string): string

One-shot: compile logic and evaluate it against data, returning the result as a JSON string.

engine.evalStr('{"var": "name"}', '{"name": "Alice"}');          // "\"Alice\""
engine.evalStr('{"map": [[1,2,3], {"+": [{"var": ""}, 1]}]}', '{}'); // "[2,3,4]"

evalMetered(logic: string, data: string, budget?: number): string

One-shot metered evaluation. Returns a JSON string {"result": <value>, "ops": <number>}. budget caps the operations the rule may charge for this call; omit it to use the engine’s config.ops_budget, and omit both to meter without a cap. A budget must be a whole number >= 1. Crossing it throws an Error named BudgetExceeded carrying budget and spent; see Operation Budget.

engine.evalMetered('{"map":[{"var":"xs"},{"*":[{"var":""},2]}]}', '{"xs":[1,2,3]}');
// '{"result":[2,4,6],"ops":10}'

evaluateWithTrace(logic: string, data: string, mode?: string): string

Evaluate with a step-by-step execution trace, honoring this engine’s templating flag, config, and custom operators. mode is "engine" (the default), "strict" or "template", as for check, so a rule you compile with compileTemplate can be traced as one. The engine compiles the rule with optimization disabled so every operator records a step; use it for debugging, not hot paths.

Returns: JSON string containing a TracedResult:

interface TracedResult {
  result: any;                        // Evaluation result (null on failure)
  expression_tree: ExpressionNode;    // Compile-time tree of the expression
  steps: Step[];                      // Execution steps, in evaluation order
  pointers?: Record<string, string>;  // Node id -> JSON Pointer into the rule as written
  error?: string;                     // Present on failure: the message
  structured_error?: StructuredError; // Present on failure: the structured form
}

interface ExpressionNode {
  id: number;                 // Compiled-node id; matches Step.node_id
  expression: string;         // Source text of this node
  children: ExpressionNode[];
}

interface Step {
  step_id: number;
  node_id: number;
  context: any;           // Data context the node saw
  result: any | null;     // The node's result; null when the step failed
  error: string | null;   // Failure message; null when the step succeeded
  iteration_index?: number;
  iteration_total?: number;
}

interface StructuredError {
  type: string;           // Stable tag: "Thrown", "InvalidOperator", "ParseError", ...
  message: string;
  operator?: string;      // Innermost failing operator
  node_ids?: number[];    // Breadcrumb from the failure site toward the root
  // plus kind-specific extras: thrown, variable, index, length, ...
}

Things to know about the shape:

• Literals never record a step. Only operator nodes (including var) appear in steps, so a rule with literal operands has fewer steps than it has JSON nodes.
• Node ids are assigned at compile time, children first, so the root of the tree is the highest id. id: 0 with an empty expression is only the placeholder returned when compilation itself fails.
• pointers places each node in the rule as written: every node id maps to the RFC 6901 JSON Pointer of the rule value it was compiled from ("/and/1", "" for the root). It is absent when the rule does not compile.
• result keeps its object key order.

Failures do not throw: result is null, error carries the message, and structured_error the structured form. An unknown mode does throw (ParseError).

The TracedResult JSON layout is the JavaScript-side wire shape, shared by every binding and described by schemas/trace.v1.json in the repository. On the Rust side it is produced from a datalogic_rs::TracedRun<String> (see the Rust API reference).

Example:

const trace = engine.evaluateWithTrace(
  '{"and": [true, {"var": "x"}]}',
  '{"x": false}'
);

const data = JSON.parse(trace);
console.log(data.result);             // false
console.log(data.steps.length);       // 2 (var lookup, then and; the literal true records no step)
console.log(data.expression_tree.id); // 4 (the root; the var node is id 3)
console.log(data.pointers['3']);      // "/and/1"

// A failing rule reports the error inside the envelope instead of throwing
const failed = JSON.parse(engine.evaluateWithTrace('{"throw": "boom"}', '{}'));
console.log(failed.result);                 // null
console.log(failed.error);                  // 'Thrown: {"type":"boom"} (in operator: throw)'
console.log(failed.structured_error.type);  // "Thrown"

const strictEngine = new Engine({ config: { preset: 'strict' } });
const run = JSON.parse(strictEngine.evaluateWithTrace('{"+": [null, 1]}', '{}'));
run.structured_error.thrown; // { type: "NaN" }

session(): Session

Open a hot-loop Session bound to this engine.

operators(): string

Every built-in operator this engine evaluates (following its families), as a JSON array in the schema of the operator catalogue:

JSON.parse(engine.operators()).find((op) => op.name === 'reduce');
// { name: "reduce", aliases: [], family: "Core", feature: null, min_args: 2, max_args: 3,
//   reads_context: false, effect: "pure", cost: "per_item", scoped_arg: 1 }

truthy(value: string): boolean

Whether the JSON value is truthy under this engine’s configured truthiness (the rules if, and, or and session.evaluateTruthy apply). Under the default rules an empty object is falsy, like an empty array. Malformed JSON throws a ParseError.

engine.truthy('{}');  // false
engine.truthy('[0]'); // true
engine.truthy('"0"'); // true (a non-empty string)

customOperatorNames(): string[]

Names of the custom operators registered on this engine (order is not guaranteed). The module-level builtinOperatorNames() lists the built-ins.

engine.customOperatorNames();       // ["double"]
new Engine({}).customOperatorNames(); // []

free(): void

Release the engine’s WASM memory eagerly. A FinalizationRegistry also reclaims every class in this package when the JS object is garbage-collected, but that is best-effort; call free() on objects you create often (per render, per request). A freed object throws on use.

Rule

A rule compiled by engine.compile() (or compileTemplate, compileStrict, compileChecked). It keeps access to its engine’s custom operators and config.

• evaluate(data: string): string - evaluate against a JSON data string
• evaluateData(handle: DataHandle): string - evaluate against a DataHandle
• evaluateMetered(data: string, budget?: number): string - evaluate under an operation budget, returning {"result": ..., "ops": N} as for evalMetered
• facts(): string - what the rule reads and calls, as JSON (below)
• free(): void

const rule = engine.compile('{">=": [{"var": "user.age"}, 18]}');
rule.evaluate('{"user": {"age": 21}}'); // "true"

facts() describes the compiled rule, after the optimizer, without running it:

JSON.parse(engine.compile('{"+": [{"var": "a.b"}, {"var": "c"}]}').facts());
// { reads: [["a", "b"], ["c"]], computed_reads: false, reads_complete: true,
//   reads_data: true, operators: ["+", "val"], custom_operators: [], deterministic: true }