jsonata2py

JSONata for Python — translated to Python source, not interpreted.

Each expression is parsed, optimised and translated into real Python code, compiled in memory, and handed back as a ready-to-call object. Evaluation is ~47x faster than the pure-Python reference interpreter, and ~2x-4x faster than both Rust-backed alternatives on this benchmark — including on JSON text in, JSON text out (see the benchmarks).

import jsonata2py as jsonata

expr = jsonata.compile("$sum(Order.Product.(Price * Quantity))")

expr.evaluate({
    "Order": {"Product": [
        {"Price": 10.0, "Quantity": 2},
        {"Price": 5.0, "Quantity": 4},
    ]}
})
# -> 40

• Pure Python, no build step. One wheel, every platform; regex is the only dependency.
• Complete. All 1,281 files of the official JSONata test suite pass.
• Typed. Ships py.typed; the source is clean under mypy --strict and ruff.
• Thread-safe and asyncio-safe. Compile once at startup, evaluate from anywhere.
• Batteries included. Typed bindings, injectable Python functions, JSONata libraries, evaluation timeouts, and access to the generated source.

Contents

• Requirements · Getting started · Exception types
• Bindings — per-evaluation, permanent, functions as values, signatures
• JSONata libraries — providing bindings, what a definition can contain
• Advanced usage — timeouts, generated source
• Performance — vs. other PyPI implementations, why it wins, break-even
• Choosing between jsonata2py and the alternatives
• Thread safety · Architecture · Package structure · License

Port of jsonata-jvm-compiler (Java) — same pipeline, same design, a different host runtime.

Requirements

Getting started

1. Install

pip install jsonata2py

2. Compile an expression

import jsonata2py as jsonata

expr = jsonata.compile("Account.Order.Product.Price * 1.2")

compile() runs the full pipeline once and returns a reusable, thread-safe object. Compile expressions at startup and reuse them for every request — do not call compile() on the hot path.

jsonata.compile() is a module-level convenience backed by a lazily-created, process-wide JsonataExpressionFactory. For repeated compilation in a hot path, or anything beyond a script, construct your own factory and reuse it:

factory = jsonata.JsonataExpressionFactory()
expr = factory.compile("Account.Order.Product.Price * 1.2")
exprs = factory.compile_all([
    "Account.Order.Product.Price * 1.2",
    "$sum(items.price)",
    'status = "active"',
])

compile_all exists for API parity with the Java library, where batching many expressions into one javac invocation was worth roughly 10x. There is no equivalent win here — Python's compile() builtin costs microseconds to low milliseconds per call regardless of batching — so compile_all is implemented as a plain loop and kept only so code written against both libraries compiles unchanged.

3. Evaluate against data

input_data = {
    "Account": {
        "Order": {
            "Product": {"Price": 50.0}
        }
    }
}

result = expr.evaluate(input_data)  # -> 60.0

evaluate() accepts and returns plain Python values: dict, list, str, int, float, bool, None (JSON null), or jsonata.MISSING (JSONata's undefined — never conflated with None). The same CompiledExpression instance can be evaluated concurrently from multiple threads.

Exception types

try:
    expr = factory.compile(expression)
    result = expr.evaluate(data)
except jsonata.JsonataCompilationError as e:
    ...  # bad expression -- e.error_code, e.message, e.__cause__ carries a ParseError with source position
except jsonata.JsonataEvaluationError as e:
    ...  # bad input or runtime error -- e.error_code is a JSONata error code like "T2001"

JSONata language features

The library implements all JSONata language features, functions as first-class values included: a function can be stored in a variable, put in an array or object, passed to and returned from another function, and carried across the binding boundary in either direction — see Functions as values.

Bindings

Bindings let you inject named values and Python functions into an expression at runtime. Inside the expression they are referenced as $name (values) or called as $name(args...) (functions).

Per-evaluation bindings

Pass a JsonataBindings instance as the second argument to evaluate() to supply values or functions for a single call:

expr = factory.compile("$taxRate * subtotal")

bindings = jsonata.JsonataBindings().bind_value("taxRate", 0.2)

result = expr.evaluate({"subtotal": 500}, bindings)  # -> 100.0

Per-evaluation bindings are not stored on the expression instance and do not affect other calls.

Permanent bindings

Use assign() and register_function() to attach bindings permanently to an expression instance. They apply to every subsequent evaluate() call.

expr = factory.compile("$round2($taxRate * subtotal)")

# Permanent value
expr.assign("taxRate", 0.2)

# Permanent function
@jsonata.bound_function("<n:n>")
def round2(n: float) -> float:
    return round(n, 2)

expr.register_function("round2", round2)

r1 = expr.evaluate({"subtotal": 100})  # -> 20.0
r2 = expr.evaluate({"subtotal": 333})  # -> 66.6

Permanent bindings are isolated per instance — assigning to one CompiledExpression does not affect any other.

Precedence

When both a permanent binding and a per-evaluation binding exist for the same name, the per-evaluation binding wins.

Functions as values

A bound function is not only callable — $name on its own is a function value, so it can be passed to a higher-order built-in, piped through ~>, or handed to another bound function:

bindings = jsonata.JsonataBindings().bind_function("double", doubler)

factory.compile("$map([1,2,3], $double)").evaluate(data, bindings)  # -> [2, 4, 6]
factory.compile("5 ~> $double").evaluate(data, bindings)            # -> 10
factory.compile("$type($double)").evaluate(data, bindings)          # -> "function"

This is what makes a library export usable as an argument as well as a call target, since exports are supplied through register_function.

The reverse also holds: a function value can be bound with bind_value and called by name. jsonata2py.runtime.lambdas.lambda_node builds one from a Python callable, with the number of parameters it takes:

from jsonata2py.runtime.lambdas import lambda_node

times_ten = lambda_node(lambda x: x * 10, 1)

bindings = jsonata.JsonataBindings().bind_value("f", times_ten)

factory.compile("$f(3)").evaluate(data, bindings)          # -> 30
factory.compile("$map([1,2], $f)").evaluate(data, bindings)  # -> [10, 20]

Both maps are consulted, and the one that matches the position wins: $name in value position prefers a value binding, $name(...) at a call site prefers a function binding.

Arity. How many arguments reach a bound function used as a value is decided by its declared signature — <nn:b> makes a two-argument function, so $sort([2,3,1], $desc) receives a comparator pair and $map supplies the index. A signature that does not pin the arity down (absent, unparseable, or variadic) yields a one-argument function value. This is the same limitation hand-written JSONata lambdas have: a packed argument tuple is an array, and so is a single array argument. Declare a fixed arity to receive several arguments.

Implementing a bound function

Two ways to bind a Python function:

The bound_function decorator — plain positional arguments, the signature declares the arity:

@jsonata.bound_function("<n:n>")
def round2(n: float) -> float:
    return round(n, 2)

A JsonataBoundFunction-shaped object — for cases needing access to the raw JsonataFunctionArguments (out-of-range access returns jsonata.MISSING rather than raising):

class Adder:
    def get_function_signature(self) -> str | None:
        return "<nn:n>"

    def apply(self, args: jsonata.JsonataFunctionArguments):
        return args.get(0) + args.get(1)

Either form may raise JsonataEvaluationError from apply/the function body.

Function signature syntax

The signature has the form <params:return> where params is a sequence of type symbols and return is a single type symbol.

Simple types

Complex types

Parametrised types: a<s> (array of strings), a<x> (array of any type), f<n:n> (a function from number to number). A parametrised f requires a function, but the argument function's own parameter and return types are not checked — jsonata-js does not check them either.

An argument declared f that is not a function is rejected with T0410. Note that j is documented by the JSONata spec as excluding functions but does not reject one here; declare f when you require a function.

Option modifiers appended to a type symbol:

Example: $length has signature <s-:n> — accepts a string (using context as focus if omitted) and returns a number.

JSONata libraries

The bindings above are written in Python: a bound function per function, an assign per value, repeated for every expression that needs them. A library is the same set of bindings written in JSONata instead — once, in one file — and applied to any expression that needs it.

A library is nothing more than a definition expression: ordinary JSONata that binds names and returns the names to export.

(
  $vatRate := 0.2;
  $round2  := function($n){ $round($n, 2) };
  $gross   := function($net){ $round2($net * (1 + $vatRate)) };
  $format  := function($n){ "£" & $string($round2($n)) };

  ["gross", "format", "vatRate"]
)

That is a complete, valid JSONata expression. Evaluate it in any JSONata engine and it returns ["gross", "format", "vatRate"] — the export list is the expression's result, not a parameter passed from Python. So a definition file can be linted, tested and run by tools that know nothing about this library, and it states its own interface: nothing outside it decides what it provides.

billing = factory.compile_library(definition)

billing.functions   # dict[str, JsonataBoundFunction] -- gross, format
billing.constants    # dict[str, Any]                  -- vatRate

Each exported name lands in one dict or the other according to what it evaluated to — the definition never says which is which. Names it binds but does not export ($round2 here) stay private, while remaining reachable from the exported functions.

Providing bindings from a library

use_library applies a whole library, functions and constants together, so the caller never has to know which name is which. On the expression it is permanent, for the lifetime of that instance:

invoice = factory.compile("lines.$gross(amount) ~> $sum() ~> $format()")

invoice.use_library(billing)

or per evaluation, when different calls need different libraries:

bindings = jsonata.JsonataBindings().use_library(billing)

invoice.evaluate(data, bindings)

It returns the same JsonataBindings, so libraries and one-off bindings compose in a single expression:

bindings = (
    jsonata.JsonataBindings()
    .use_library(billing)
    .use_library(formatting)
    .bind_value("today", today)
)

Applying two libraries that export the same name leaves the later one in place, exactly as re-binding a name always does.

Either way the expression sees $gross(...), $format(...) and $vatRate exactly as if they had been written in Python — the precedence rules above apply unchanged, so a per-evaluation binding still wins over a library one registered permanently.

Applying a library to every expression in an application is one line each:

for expr in factory.compile_all(expressions):
    expr.use_library(billing)

What a definition can contain

Anything JSONata can express. Exported functions may be recursive, mutually recursive, closures over private helpers, λ-notation, functions returned by other functions, ~> chains, or partial applications:

(
  $pi := 3.1415926535897932384626;

  /* private helpers — not exported, still reachable */
  $product   := function($a, $b) { $a * $b };
  $factorial := function($n) { $n = 0 ? 1 : $reduce([1..$n], $product) };

  $sin := function($x){ $cos($x - $pi/2) };
  $cos := function($x){
    $x > $pi ? $cos($x - 2 * $pi) : $x < -$pi ? $cos($x + 2 * $pi) :
      $sum([0..12].($power(-1, $) * $power($x, 2*$) / $factorial(2*$)))
  };

  ["sin", "cos", "pi"]
)

Constants are values, not expressions: the definition runs once, when the library is compiled, so $total := $sum([1..10]) exports the number 55. Functions, by contrast, run whenever they are called.

The export list is itself an expression — ["sin", "cos"] is the usual form, a single "sin" works, and so does a list computed at definition time. A definition that forgets its export list ends on its last binding and therefore returns a function; that is rejected with must return an array of function names.

Exported functions can also be called straight from Python, with no expression involved:

gross = billing.functions["gross"]
result = gross.apply(jsonata.JsonataFunctionArguments([100]))

Signatures

Each exported function reports a JSONata signature:

The synthesised form is deliberately permissive: JSONata lets a lambda be called with fewer arguments than it declares (the rest are undefined), and j applies no coercion — so an exported function accepts exactly what the same function accepts inside JSONata. Ask for something stricter with a signature override:

lib = factory.compile_library(
    definition,
    jsonata.JsonataLibraryOptions().with_signature("$gross", "<n:n>"),
)

# "<n:n>" coerces at the boundary: $gross("100") works

Lifetime and options

A library owns one generated module, so build it once at startup and keep it — the same advice as compile(). Exported functions are thread-safe and may be called concurrently.

JsonataLibrary supports the with statement; close() retires the exported functions (calling one afterwards raises JsonataEvaluationError), which is only worth doing when the lifetime should be explicit. Constants keep working — they are ordinary values. Letting the library become unreachable releases everything.

JsonataLibraryOptions also carries the document the definition is evaluated against (with_input, for a definition that reads from data) and the bindings visible while it runs (with_bindings).

A definition must be self-contained

Every name a definition uses has to come from somewhere it controls: a name it binds itself, a JSONata built-in, or a name handed to it at build time. Anything else is rejected when the library is compiled:

($withVat := function($net){ $net * (1 + $vatRate) }; ["withVat"])

-> JsonataCompilationError: The definition expression uses $vatRate, which it does not bind
   and which is not a JSONata built-in. Bind it in the definition, or supply it through
   JsonataLibraryOptions.bindings.

The alternative — resolving $vatRate against whatever happens to be bound where $withVat is called — would make a library's behaviour depend on its caller, and would make a typo ($rat for $rate) indistinguishable from a deliberate hook. Failing at build time names both the problem and the fix.

To parameterise a library, supply the values when you build it:

lib = factory.compile_library(
    definition,
    jsonata.JsonataLibraryOptions().with_bindings(
        jsonata.JsonataBindings().bind_value("vatRate", rate)
    ),
)

Those names are then in scope for the definition, and are captured by the functions it exports.

Lambda parameters, bindings inside nested blocks, forward references between siblings (mutual recursion), and path bindings (@$v, #$i) all count as bound — only genuinely unresolvable names are reported.

One further semantic worth knowing: the caller's evaluation is reused. Called from inside an expression, an exported function shares that evaluation's recursion budget (100 nested calls) and its set_timeout deadline.

Advanced usage

Evaluation timeout

Call set_timeout(timeout_ms) on an expression instance to cap how long a single evaluate() call may run. If the deadline is exceeded, a JsonataEvaluationError with error code U1001 is raised.

expr = factory.compile("...")
expr.set_timeout(500)  # 500 ms wall-clock limit per evaluate() call

try:
    result = expr.evaluate(data)
except jsonata.JsonataEvaluationError as e:
    if e.error_code == "U1001":
        ...  # evaluation exceeded 500 ms

Pass 0 to remove the timeout. The timeout applies to all future evaluate() calls on the instance; concurrent calls on the same instance each track their own independent deadline (per-evaluation state lives in a contextvars.ContextVar, not shared mutable state — see Thread safety). Setting a timeout has no measurable overhead on evaluations that complete before the deadline.

Inspecting the source expression

expr = factory.compile("$sum(items.price)")
print(expr.source_jsonata)  # -> "$sum(items.price)"

Accessing the generated Python source

factory.translate() runs the pipeline up to source generation without compiling it — useful for debugging or inspection. The output format is unstable across versions.

python_source = factory.translate("price * qty")
print(python_source)

Loading pre-generated Python source

If you have previously generated and saved a source string, load it directly without re-parsing:

from jsonata2py.loader.loader import ExpressionLoader

loader = ExpressionLoader()
entry_point, source_jsonata = loader.load(python_source)

Performance

jsonata2py translates each expression to Python source once, then evaluates that compiled code many times. Compilation costs more than the alternatives; evaluation costs less. Everything below follows from that trade.

Measured against the other PyPI implementations

Same expression, same input document, same acceptance check — all four produce identical, verified-correct output. The workload is the analytical benchmark the Java sibling project uses: variable bindings, nested navigation, array filtering, $sum, $count, $average, $max, $min, $distinct, string operations, arithmetic and a conditional.

Versions measured: jsonata2py 0.1.1, jsonatapy 2.2.7, jsonata-rs 0.1.4, jsonata-python 0.7.0 — each the latest release on PyPI when these numbers were taken (evaluation re-measured 2026-09-01, after the conformance fixes for $spread, nested wildcard paths, and builtin context substitution in version 0.1.1).

† jsonata-rs and jsonata-python both install a top-level module named jsonata and therefore cannot coexist in one environment, so the jsonata-rs column (here and in the tables below) is carried over from the 2026-08-24 session on the same machine, with its relative figures recomputed against the current jsonata2py number. The other three columns were measured in a single run, with all three outputs asserted identical first.

Why a pure-Python library beats two native ones here

This is the part worth understanding before you trust the table, because "pure Python beats Rust" is not a claim that should be taken at face value.

Two separate effects stack up, and it is worth keeping them apart.

The compiled Python code is genuinely fast. Translation removes per-node visitor dispatch, per-element callback frames and repeated type re-checking — see Where the speed comes from. In CPython a function call costs ~85 ns and cannot be inlined away, so a tree-walking interpreter's per-node overhead is irreducible, while generated straight-line code simply does not pay it.

On top of that, a native extension has to move your data across the FFI boundary. Every evaluate() call converts the input dict into the extension's own value representation and converts the result back. That cost scales with the size of the data, not the complexity of the expression. jsonata2py generates Python code that reads the objects you already have — it converts nothing.

The second effect is why the margin widens with document size. On $sum(items.value), a deliberately trivial expression that gives the compiled code almost nothing to win back:

jsonata2py leads at every size, and its lead over jsonatapy grows from 1.27x at n=10 to 2.53x at n=10 000 — the marshalling tax becoming visible as the document grows.

Two claims that earlier versions of this section made are no longer true, and are recorded here because they were the section's own supporting evidence:

• It used to say that giving jsonatapy a path that avoids the boundary lets it win. It no longer does. evaluate_json() takes JSON text and returns JSON text, never materialising a Python object graph, and that is the comparison most favourable to it — yet jsonata2py doing json.loads → evaluate → json.dumps is 183 µs against its 255 µs, still 1.39x ahead.
• It used to say that on a trivial expression jsonatapy is ~1.15-1.3x faster, because there is barely any evaluation work to win back. The table above is that same measurement, and the ordering has inverted at every size.

Both reversals come from the same place: the optimization pass in docs/design/PERFORMANCE-REVIEW.md review #3, which cut evaluation on the main benchmark by 1.9x and $sum(x.field) specifically by 2.3x.

The honest summary is still narrower than "faster than Rust": jsonata2py is fastest when you evaluate a compiled expression against Python objects you already hold, which is the common case for a JSONata library embedded in a Python service. Where a native library can still win is a workload that compiles constantly and evaluates rarely — its compile step is 27x cheaper, so see the break-even below.

When compilation pays for itself

Compilation is a one-time cost; evaluation is what repeats. Dividing the extra compile time by the per-evaluation saving gives the break-even point on this workload — every figure below is derived from the table above, so it moves with it:

Compile once at startup, evaluate on the hot path, and the compilation cost stops mattering after a few dozen calls. Compile inside a request handler and you pay it every time — see the guidance below.

Repeat compilation of the same text

Compiling the same expression text again is far cheaper than the table suggests, in two tiers. While an earlier CompiledExpression for that text is still reachable, a repeat compile() reuses its entry point and costs ~0.9 µs. Once that has been collected, the factory still holds the compiled code object, and re-executing it into a fresh module namespace costs ~20 µs rather than re-running the whole pipeline — the case a long-lived process actually hits when it compiles an expression, uses it, drops it, and meets the same text again later.

Neither tier can leak. The first holds only a weak reference to the entry point. The second holds a code object, which references neither a module namespace nor a CompiledExpression, so dropping every reference to one still leaves its generated module fully collectible (tests/test_memory.py asserts exactly this). The code-object tier is bounded by generated-source bytes rather than entry count, because generated modules differ in size by two orders of magnitude.

This does not relax the "don't call compile() on the hot path" guidance: text the cache has never seen, or has already evicted, still pays full price.

Where the speed comes from

Compile-time work that a tree-walking interpreter repeats on every evaluation: per-node visitor dispatch and type-check chains disappear; a JSONata variable becomes a Python local; a built-in call resolves directly to the runtime function the translator already chose, with no re-dispatch; and/or are emitted as Python's own short-circuiting operators rather than helper calls taking a closure per operand; sorting uses a native key-sort instead of a comparator callback wrapped in functools.cmp_to_key; and fused aggregate paths ($count(x[field = "value"]), $sum(x.field)) run as a single loop with no intermediate list.

Runtime work that review #3 removed, all of it in the same spirit — CPython cannot inline a small function, so the fix is to not call one:

• Fused aggregate and count helpers are monomorphized per value kind, so a per-element comparison is a branch in one loop rather than a closure reached through a helper. sum(1 for ...) became a plain for, because PEP 709 inlines comprehensions but not generator expressions — a genexpr costs a frame resume per element.
• eq/ne settle scalar comparisons inline instead of delegating to the recursive deep-equality walk, whose own first act was the same type test.
• $distinct deduplicates scalars through a set per JSONata kind and buckets composites by a structural hash, replacing a pairwise scan that was O(n²).
• The delegating built-ins in core.py no longer re-execute an import statement on every call, and the timeout guard no longer does a ContextVar lookup per callback-taking helper.

On the comparison with the Java sibling. Its headline is ~40x over JSONata4Java and this port now measures ~47x over jsonata-python, but those ratios are not comparable: each divides by a different interpreter, and jsonata-python is the slower baseline of the two. The Java number comes from JIT-compiled bytecode replacing an AST walker; CPython has no JIT, so generated Python source runs on the very same interpreter an AST walker would. The win here is entirely the removal of per-node and per-element overhead listed above — which turns out to be worth about as much, proportionally, as the JVM's machine code.

Unlike the Java library, batching many compile() calls into compile_all is not a meaningful win here — see Compile an expression.

Reproducing these numbers

pytest tests/benchmarks -m benchmark

Measured on an Intel Core i7-1185G7 @ 3.00 GHz (4 cores), Windows 11, CPython 3.14.3. Methodology, because cross-library benchmarks are easy to get wrong:

• Each implementation runs in its own process. Measuring them in one interpreter made jsonata-python look 2.5x slower than it is — discarded compiled modules from jsonata2py's cold-compile rounds created GC pressure that landed on whichever allocation-heavy library was measured next.
• Trials are interleaved (round-robin, repeated) so slow machine drift affects every library equally instead of favouring whichever ran first. The minimum across trials is kept; noise only ever adds time.
• jsonata2py's compile cache is deliberately defeated for the compile row (a fresh factory plus a unique inert comment), so it is a genuine cold compile measured against libraries that have no cache at all.
• jsonata-rs and jsonata-python were measured in separate virtualenvs, for the reason in the next section, with jsonata2py present in both as the anchor used to normalise across them.
• The 2026-08-31 re-measurement used a single process with gc.collect() plus gc.disable() inside each timed round and the minimum of nine rounds, no cold-compile rounds interleaved with evaluation rounds. That it reproduced the previously published separate-process figures for the two libraries that did not change — jsonatapy 257→275 µs, jsonata-python 5 471→5 518 µs — is the evidence that the single-process shortcut did not bias the comparison. The GC interference described in the first bullet comes specifically from mixing compile rounds into an evaluation measurement, which this run does not do.

Timings are not portable between machines. Regressions against your own baseline are gated by an opt-in check: pytest tests/benchmarks -m perfgate --perf-record to record, then -m perfgate to enforce. Baselines are not committed.

Choosing between jsonata2py and the alternatives

Use jsonata2py when you evaluate the same expression many times against Python objects. That is where the design pays: compile once at startup, then every evaluation runs generated Python code directly over the dicts and lists you already have, with no marshalling and no AST walk. Concretely, it is the right default if you hold a compiled expression on a service, a worker, or a pipeline stage and call it per request, per row, or per message — and especially if you want no native dependency, no build toolchain, and one wheel that installs everywhere. It is also the only one of the four with typed bindings, injectable Python functions, JSONata libraries, an evaluation timeout, and full mypy --strict coverage, so it fits best when JSONata is a first-class part of your application rather than an occasional utility call.

Prefer jsonatapy for short-lived work where compilation dominates: its cold compile is ~26x cheaper, so under ~49 evaluations of a given expression it comes out ahead. That is the one workload shape where it clearly wins — a CLI, a lambda, or anything that compiles an expression, uses it a handful of times, and exits. It also ships Windows wheels and has the broadest wheel coverage of the native options.

Two reasons to reach for it that this README used to give no longer hold: its text-in/text-out evaluate_json() is no longer faster than jsonata2py doing json.loads → evaluate → json.dumps (255 µs against 183 µs), and it is no longer faster on simple expressions over small documents either — see the scaling table.

Prefer jsonata-rs if you specifically want its Rust implementation of the jsonata-java reference semantics and you are on Linux or macOS. Be aware of two practical constraints: it publishes no Windows wheel, so Windows users need a Rust toolchain to install it at all; and it installs a top-level module named jsonata — the same name jsonata-python uses — so the two silently overwrite each other and cannot coexist in one environment. On this workload it measured ~4x slower than jsonata2py.

Prefer jsonata-python when you want the closest thing to the reference implementation and performance genuinely does not matter — a one-off script, a test fixture, a CLI that evaluates an expression once and exits. It is a pure-Python AST interpreter, which makes it easy to read and debug, but it evaluates ~47x slower than jsonata2py here and compiles more slowly, so there is no workload shape where it is the faster choice.

Thread safety

A JsonataExpressionFactory instance and all CompiledExpression instances it produces are fully thread-safe. evaluate() is stateless — each call reads the input independently and returns a new value without modifying any shared state. Per-evaluation state (bindings overlay, timeout deadline, call depth) lives in a contextvars.ContextVar, which is also what makes evaluation correct across asyncio tasks, not just OS threads: each task runs in its own copied context.

# Compile once at startup
total_price = factory.compile("$sum(items.(price * qty))")

# Call concurrently from any number of threads
import concurrent.futures
with concurrent.futures.ThreadPoolExecutor(max_workers=16) as pool:
    pool.submit(total_price.evaluate, request_data)

Architecture overview

expression string
       |
       v
  Parser.parse()                  -> AstNode (frozen dataclass hierarchy)
       |
       v
  optimize()                      -> AstNode (constant-folded, simplified)
       |
       v
  Translator.translate()          -> Python 3.11+ source string
       |
       v
  ExpressionLoader.load()         -> CompiledExpression (compiled, in-memory)
       |
       v
  expr.evaluate(data)             -> a plain Python value

JsonataExpressionFactory.compile() runs this entire pipeline in a single call.

Package structure

Sibling implementations

The same parse → optimise → translate → compile pipeline exists for three host runtimes:

The JVM implementation is the original, and is the compiler behind valem.run's reactive computation engine.

License

MIT — see LICENSE.