seuil

A complete, safe JSONata implementation in Rust — JSON query, transform, and expression evaluation.

Documentation | Crate | Repository | Changelog

Seuil (French: "threshold") is a JSONata query and transformation engine for Rust. Compile a JSONata expression once, then evaluate it against any JSON input — fast, safe, and spec-compliant.

use seuil::Seuil;

let expr = Seuil::compile("orders[status='paid'].amount ~> $sum()")?;

let data = serde_json::json!({
    "orders": [
        {"status": "paid", "amount": 100},
        {"status": "pending", "amount": 50},
        {"status": "paid", "amount": 200}
    ]
});

let result = expr.evaluate(&data)?;
assert_eq!(result, serde_json::json!(300.0));

Why seuil?

• 99.6% JSONata spec compliance — 1,027 of 1,031 official test cases pass
• Zero unsafe — #![forbid(unsafe_code)] enforced at the crate level
• Zero panics on any input — malformed expressions and data return Err, never crash
• Compile once, evaluate many — parse the expression once, run it against thousands of inputs
• Fast-path JSON input — serde_json::Value converts directly to the arena, bypassing the expression parser
• 47 built-in functions — strings, math, arrays, objects, higher-order functions, date/time, regex
• Arena allocation — all values in a bumpalo arena for cache-friendly, zero-fragmentation evaluation
• Deterministic simulation testing — injectable Environment trait for fully reproducible evaluation

Quick Start

Add to your Cargo.toml:

[dependencies]
seuil = "0.1"
serde_json = "1"

API

use seuil::{Seuil, EvalConfig};

// Compile a JSONata expression
let expr = Seuil::compile("$.name")?;

// Evaluate against serde_json::Value
let result = expr.evaluate(&serde_json::json!({"name": "Alice"}))?;

// Evaluate against a JSON string
let result = expr.evaluate_str(r#"{"name": "Bob"}"#)?;

// Evaluate with no input
let result = Seuil::compile("1 + 2")?.evaluate_empty()?;

// Evaluate with custom config (timeouts, depth limits)
let config = EvalConfig {
    max_depth: Some(100),
    time_limit_ms: Some(1000),
    ..Default::default()
};
let result = expr.evaluate_with_config(&serde_json::json!(null), &config)?;

Built-in Functions

String

$string · $length · $substring · $substringBefore · $substringAfter · $uppercase · $lowercase · $trim · $pad · $contains · $split · $join · $replace · $match · $base64encode · $base64decode

Numeric

$number · $abs · $floor · $ceil · $round · $power · $sqrt · $random · $sum · $max · $min · $average

Array

$count · $append · $sort · $reverse · $shuffle · $distinct · $zip · $flatten

Object

$keys · $lookup · $spread · $merge · $sift · $each · $error · $assert · $type

Higher-Order

$map · $filter · $single · $reduce

Type & Logic

$boolean · $not · $exists

Date/Time

$now · $millis · $fromMillis · $toMillis

Deterministic Testing

All non-determinism ($now(), $millis(), $random(), $uuid()) is injectable via the Environment trait:

use seuil::clock::MockEnvironment;
use seuil::EvalConfig;

let env = MockEnvironment::new(0xDEAD_BEEF);
let config = EvalConfig::with_environment(&env);
// Every evaluation with the same seed produces identical results.

Comparison

Testing Rigor

seuil is tested beyond typical crate standards:

• Official test suite: 1,027 of 1,031 active JSONata test cases pass
• VOPR campaigns: 10,000+ seed verification with zero panics
• Chaos testing: 9 fault injection categories — truncation, deep nesting, huge arrays, Unicode stress, type confusion, malformed input, resource exhaustion
• Property-based testing: ~14,000 generated cases via proptest
• Coverage-guided fuzzing: libfuzzer with corpus and dictionary
• Continuous verification: GitHub Actions CI on every push, nightly fuzzing and VOPR campaigns

Use Cases

seuil was built for dental RPA and healthcare EDI processing at Zuub, where expressions evaluate thousands of eligibility responses, claims, and benefit structures:

use seuil::Seuil;

// Extract dental benefits from an eligibility response
let expr = Seuil::compile("benefitInformation[serviceType='35' and code='1'].amount")?;
let max = expr.evaluate(&eligibility_response)?;

// Get patient name
let name = Seuil::compile("subscriber.firstName & ' ' & subscriber.lastName")?;
let full_name = name.evaluate(&eligibility_response)?;

It works equally well for any JSON query and transformation task — API response processing, configuration extraction, data pipeline transforms, log analysis, and more.

Architecture

Expression String ──→ Parser (Pratt) ──→ AST ──→ Evaluator ──→ Result
                                                     │
                                          ┌──────────┴──────────┐
                                          │  bumpalo Arena       │
                                          │  (all values here)   │
                                          │  ScopeStack          │
                                          │  47 native functions │
                                          │  Environment trait   │
                                          └─────────────────────┘

• Parser: Pratt parser with operator precedence, all JSONata operators including parent (%)
• Evaluator: Recursive AST walker with tail-call optimization trampoline
• Values: Arena-allocated via bumpalo — zero per-value heap allocation, cache-friendly layout
• Scope: Stack-based variable scoping with lambda capture snapshots (no Rc<RefCell>)
• Functions: 47 built-in functions with higher-order function callback wiring

Minimum Supported Rust Version

The MSRV is 1.77.0.

License

Licensed under the Apache License, Version 2.0.

Contributing

See CONTRIBUTING for development setup, running tests, benchmarks, VOPR campaigns, and the fuzzer.