JSON Logic Documentation

JSON Logic is a format for encoding business rules as JSON objects. It provides a portable, language-agnostic way to define logic that can be evaluated consistently across different platforms—whether in Ruby on the server, JavaScript in the browser, or any other language with a JSON Logic implementation.

Structure

A JSON Logic rule is a JSON object with a single key (the operator) and a value (the arguments):

{ "operator": [argument1, argument2, ...] }

Rules can be nested—any argument can itself be another rule, allowing you to build complex expressions from simple primitives.

Data

Rules are evaluated against a data object. Use the val operator to access values from this data:

Shiny JSON Logic

shiny_json_logic is a Ruby gem that implements the JSON Logic specification with up-to-date operators. It's designed to be safe, simple and easy to use.

require 'shiny_json_logic'

rule = { ">" => [{ "val" => "age" }, 18] }
data = { "age" => 25 }

ShinyJsonLogic.apply(rule, data)  # => true

# Aliases for easier migration from other gems
JsonLogic.apply(rule, data)   # => true
JSONLogic.apply(rule, data)   # => true

Why Shiny JSON Logic?

shiny_json_logic is the only Ruby gem that evaluates JSON Logic rules exactly as its counterparts in languages like JS or Python and is also the fastest one by far in the Ruby ecosystem. See the benchmarks or the comparison on the homepage.

JSON Logic uses specific rules to determine if a value is considered "truthy" (treated as true) or "falsy" (treated as false). These rules are important for logical operators like and, or, if, and !.

When you evaluate a JSON Logic rule, you provide a data object. This object becomes the root context—the starting point for all variable access.

Root Context

At the top level, val and var access values directly from your data object.

Stacked Contexts (Inside Iterators)

When you use iterators like map, filter, or reduce, a new context is pushed onto the stack. The current item becomes the new context, and the previous context moves "up" one level.

Data: { "users": [{"name": "Alice"}, {"name": "Bob"}], "greeting": "Hello" }

Inside map, the context stack looks like:
┌───────────────────────────────────────┐
│ Level 0 (current): {"name": "Alice"}  │  ← {"val": "name"} or {"val": []}
├───────────────────────────────────────┤
│ Level 1: {index: 0}                   │  ← {"val": [[1], "index"]}
├───────────────────────────────────────┤
│ Level 2 (root): {users, greeting}     │  ← {"val": [[2], "greeting"]}
└───────────────────────────────────────┘

JSON Logic provides a rich set of operations organized into categories:

• Variable Access — var, val
• Logical — and, or, ??, !, !!
• Control Flow — if, ?:
• Comparison — ==, ===, !=, !==, >, >=, <, <=
• Arithmetic — +, -, *, /, %, min, max
• String — cat, substr, in
• Array — map, filter, reduce, all, some, none, merge
• Data Validation — exists, missing, missing_some
• Error Handling — try, throw

Each operation follows the same pattern: {"operator": arguments}. Arguments can be literal values or nested operations.

Retrieves a value from the data object using dot notation for nested access. This is the most fundamental operation in JSON Logic - it's how you access your data.

Basic Usage

Access a top-level key from your data:

Dot Notation for Nested Access

Use dots to traverse nested objects. The path user.profile.email will access data["user"]["profile"]["email"].

Default Values

Provide a fallback value as the second element in an array. If the key doesn't exist or is null, the default is returned instead.

Empty String - Get Entire Data

Passing an empty string "" or null returns the entire data object. This is especially useful inside iterators.

The recommended way to access values from the data object. Uses an array of keys for nested access and supports scope navigation in iterators.

Basic Usage

Access values using a single key or an array of keys for nested access:

Array Notation for Nested Access

Use an array of keys to traverse nested objects. Each element in the array is a key to traverse, so ["user", "profile", "email"] accesses data["user"]["profile"]["email"].

Scope Navigation

Inside iterators like map or filter, val can navigate up the scope stack using the special syntax [[N], "key"] where N is the number of levels to go up.

Empty Array - Get Current Scope

Passing an empty array [] returns the current scope's data.

Returns the first falsy value, or the last value if all are truthy. Uses short-circuit evaluation—stops as soon as it finds a falsy value.

Returns the first truthy value, or the last value if all are falsy. Uses short-circuit evaluation—stops as soon as it finds a truthy value.

Returns the first non-null value from a list of arguments. Similar to or, but only checks for null instead of falsy values.

Negates the truthiness of a value. Returns true if the value is falsy, false if it's truthy.

Converts any value to its boolean equivalent. Always returns exactly true or false.

Conditional branching with if/then/else logic. Supports multiple conditions (elseif) and uses lazy evaluation—only the needed branch is evaluated.

A shorthand alias for if with exactly three arguments. Mimics the ternary operator (condition ? then : else) found in many languages.

Compares two values with type coercion. Strings and numbers are compared numerically when possible.

Compares two values without type coercion. Both value and type must match.

Returns true if values are not equal (with type coercion).

Returns true if values are not strictly equal (no type coercion).

Tests if the first value is greater than the second.

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

Tests if the first value is less than the second.

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

Adds numbers together. With a single argument, converts the value to a number. An empty array returns 0 (additive identity).

Subtracts numbers. With a single argument, negates the value.

Multiplies numbers together. An empty array returns 1 (multiplicative identity).

Divides numbers.

Returns the remainder after division. The sign of the result follows the dividend (first operand), matching Ruby's remainder behavior.

Returns the smallest value from a set of numbers.

Returns the largest value from a set of numbers.

Concatenates values into a single string.

Extracts a portion of a string. Takes the source string, a start index, and an optional length.

Checks if a value exists within a string (as a substring) or within an array (as an element). The first argument is the needle, the second is the haystack.

Flattens and merges multiple arrays into one. Non-array values are wrapped as single-element arrays.

Applies a transformation to each element in an array and returns a new array with the results.

Returns a new array containing only the elements that satisfy the given condition.

Reduces an array to a single value by applying an accumulator function to each element. Takes three arguments: the array, the reducer expression, and the initial accumulator value.

Returns true if all elements in the array satisfy the condition. Short-circuits on the first falsy result.

Returns true if at least one element in the array satisfies the condition. Short-circuits on the first truthy result.

Returns true if no elements in the array satisfy the condition. The logical opposite of some.

Checks if a path exists in the data object. Unlike var or val, this operator distinguishes between a missing key and a key that exists with a null value.

Basic Usage

Pass an array of keys representing the path to check:

Returns an array of keys that are missing from the data object. Useful for validating that required fields are present before processing.

Returns the missing keys only if fewer than the required minimum are present. Useful when you need "at least N of these fields" validation.

Syntax

{"missing_some": [minimum_required, ["key1", "key2", "key3", ...]]}

Attempts to evaluate expressions in order, catching any errors and trying the next alternative. Returns the first successful result.

Raises an error that stops evaluation and can be caught by try. The thrown value can be a string (used as the error type) or an object with custom fields.

Handling Errors in Ruby

When using shiny_json_logic in Ruby, uncaught errors raise ShinyJsonLogic::Errors::Base. You can rescue these errors and access the error type via the type attribute.

require 'shiny_json_logic'

rule = { "throw" => "ValidationError" }
data = {}

begin
  result = ShinyJsonLogic.apply(rule, data)
rescue ShinyJsonLogic::Errors::Base => e
  puts e.type  # => "ValidationError"
end