JsonLogic Overview

JsonLogic is a small, portable rule language that expresses boolean tests, arithmetic, and data lookups as plain JSON. Semantius uses it as the substrate for all four business-logic extension points, with a few Semantius-specific additions layered on top.

This page is a quick orientation. For the full operator catalog, refer to the upstream documentation:

• Project home: jsonlogic.com
• Operator reference: jsonlogic.com/operations.html

The shape of a rule

A JsonLogic expression is a single JSON object whose top-level key is the operator name and whose value is the operator’s argument list. Operators nest freely:

{ "==": [{ "var": "status" }, "active"] }

This reads as: take the value of the status field of the current row, compare it to the string "active", return true if they match.

Anything that is not an object with one of the known operator keys is returned as-is. That includes literals (42, "hello", true, null) and plain arrays.

Common operators

Operator	Purpose
var	Read a field from the current context. Dotted paths walk into nested objects: {"var": "customer.email"}.
==, !=, <, <=, >, >=	Equality and ordered comparison.
and, or, !	Boolean composition and negation.
if	Three-argument ternary: {"if": [<cond>, <then>, <else>]}. Accepts more arguments for if / elseif / else chains.
+, -, *, /, %	Arithmetic.
cat	String concatenation (treats null as "null", unlike the Semantius concat extension).
in	Membership test in an array or substring test in a string.
map, filter, reduce, all, none, some	Array combinators.
merge	Flatten arrays.
missing, missing_some	Report missing required fields.

Samples

Reject negative quantities.

{ ">=": [{ "var": "quantity" }, 0] }

Status defaults to “draft” when blank.

{ "if": [
  { "or": [{ "==": [{ "var": "status" }, null] }, { "==": [{ "var": "status" }, ""] }] },
  "draft",
  { "var": "status" }
] }

Order must have at least one line item. Using the standard missing operator to report a required field:

{ "==": [{ "missing": ["customer_id"] }, []] }

Compute total from subtotal and tax.

{ "+": [{ "var": "subtotal" }, { "var": "tax" }] }

Allowlist test.

{ "in": [{ "var": "country" }, ["US", "CA", "GB", "DE"]] }

Filter the line items array down to taxable rows.

{ "filter": [
  { "var": "line_items" },
  { "==": [{ "var": "taxable" }, true] }
] }

What Semantius adds

Semantius extends standard JsonLogic with reserved variables ($today, $now, $user_id, $old) and platform operators (let, set_record, has_permission, require_permission, value_changed, concat, is_match, throw_error). The extensions are scoped to the request the rule runs in and have no analog upstream. See JsonLogic extensions for the full list.