JSON Logic and Rule Cascade

JSON Logic is the design Rule Cascade expressions started from: logic written as JSON data, read with var, evaluated by a small interpreter that exists in many languages. This page explains why Rule Cascade nevertheless has its own expression language, and documents the converter that moves expressions between the two.

• Why Rule Cascade does not use JSON Logic
• The converter
• JSON Logic to Rule Cascade
• Rule Cascade to JSON Logic
• Caveats
• Worked examples

Why Rule Cascade does not use JSON Logic

The decision is recorded in ADR 0001. The reasons, with what each one costs:

Strict typing. A business rule decides whether an operation is allowed. In JSON Logic {"<": [{"var": "amount"}, 100]} is true when amount is missing, because null < 100 is true in JavaScript, and "17" < 18 is true as well. That is convenient for form data and risky for a decision. Rule Cascade refuses to guess: the same comparison raises an evaluation error, the rule produces a blocking finding, and the author sees it in the golden tests.

One meaning in every language. Several JSON Logic operators mean what JavaScript does: == is JavaScript's loose equality, + applies parseFloat, substr counts UTF-16 code units, and a path segment length returns the length of a list or string. A port to Java, Go or Python has to imitate JavaScript to agree, and ports differ at these edges. Rule Cascade needs a browser and a server to agree on every input, so its semantics are written down operator by operator and checked by the conformance suite.

Decimal arithmetic. Rules compare money. 0.1 + 0.2 <= 0.3 is false in binary floating point and true in decimal.

The operator as a value. With {op, args} the operator list is a JSON Schema enum, so a ruleset can be validated before it is loaded, walked for static checks (paths against the API schema, parameters, scopes), mapped to sealed types in typed languages, and produced by a language model under a strict output schema. With the operator in the key each of these needs custom code.

What surrounds the expression. JSON Logic is an expression format. A rule needs more than the expression: an id, a severity, a finding code and message, the field it points at, when it applies, whether a warning must be acknowledged or an error may be accepted with a justification, who owns it in the hierarchy and what a child may override. Rule Cascade defines those, and the expression is the small part.

What JSON Logic has that Rule Cascade does not: brevity, a large number of existing ports and editors, and tolerance for untyped input. When all that is needed is one condition shared between a JavaScript front end and a back end, JSON Logic is a reasonable choice. The converter exists so that choosing one does not lock out the other.

The converter

tools/jsonlogic.py converts in both directions. From the command line:

python tools/rulecheck.py jsonlogic import rule.json            # JSON Logic  -> Rule Cascade
python tools/rulecheck.py jsonlogic export expression.json      # Rule Cascade -> JSON Logic
cat rule.json | python tools/rulecheck.py jsonlogic import -    # - reads standard input

The converted JSON goes to standard output and warnings go to standard error. The exit status is 0 when the input was converted, 1 when it was refused (nothing is printed on standard output) and 2 when the input could not be read.

From Python:

from jsonlogic import to_rule_cascade, to_json_logic, ConversionError

expression, warnings = to_rule_cascade({"<": [{"var": "age"}, 18]}, root="data", truthiness="strict")
logic, warnings = to_json_logic(expression, root="data")      # root=None keeps the root names

Every construct is in one of three classes:

The converter never returns an expression that behaves differently without a warning. "JSON Logic" means the behaviour of json-logic-js 2.0.5, the reference implementation. tools/tests/test_jsonlogic.py evaluates every mapping with the Rule Cascade reference implementation and compares it with values json-logic-js produced for the same data (tools/tests/fixtures/jsonlogic_expected.json); for each caveat it also holds an input on which the two differ.

Whether a construct is equivalent often depends on what the converter can see. {"<": [1, 2]} compares two numbers and is equivalent; {"<": [{"var": "a"}, 2]} compares a number with a value of unknown type and carries the caveat. The tables say "known" for a type that can be read off the expression: a literal, or the result of an operator that always returns that type.

JSON Logic to Rule Cascade

missing returns the names of the missing properties, which no Rule Cascade expression can produce. Where JSON Logic only tests whether that list is empty, the meaning is "is something missing", and that converts exactly: under ! or !!, as the condition of if, as the predicate of filter, all, some or none, and as an operand of and or or in one of those places.

Truthiness

JSON Logic treats null, false, 0, "" and [] as false and everything else as true. By default the converter maps a condition to the strict operator and warns when it cannot see that the condition is a boolean: {"!": {"var": "a"}} becomes not(data.a), which is the same for true and false and an evaluation error for anything else.

With --expand-truthiness (truthiness="expand") the test is written out, which is exact for every value and needs no warning:

Use it when the JSON Logic rules being migrated test strings, numbers or lists for presence. and and or return one of their operands in JSON Logic, so expansion applies to them only where the result is itself used as a condition; elsewhere the default mapping and its warning remain.

Refused

Rule Cascade to JSON Logic

Refused

Caveats

Each warning starts with the paths it applies to ($.and[0].==) followed by one of these texts.

One difference has no warning because the converter cannot see it: json-logic-js resolves a path through any JavaScript property, so {"var": "name.0"} returns the first character of a string, where Rule Cascade returns null. Of these properties only length is detected.

Worked examples

Long lines of console output are wrapped on this page.

1. Importing an eligibility rule

{ "and": [
  { ">=": [ { "var": "age" }, 18 ] },
  { "in": [ { "var": "country" }, [ "US", "CA", "GB" ] ] },
  { "===": [ { "var": "status" }, "active" ] }
] }

$ python tools/rulecheck.py jsonlogic import eligibility.json
warning: $.and[0].>=[0]: JSON Logic converts these operands to numbers ("17" is 17, null is 0) and
compares two strings alphabetically. Rule Cascade accepts only numbers and raises an evaluation
error otherwise.

The result, written the way a ruleset would hold it:

assert:
  op: and
  args:
    - { op: gte, args: [ { var: data.age }, 18 ] }
    - { op: in, args: [ { var: data.country }, { op: list, args: [US, CA, GB] } ] }
    - { op: eq, args: [ { var: data.status }, active ] }

in with a literal list and === are equivalent and convert silently. The warning is about age: JSON Logic accepts "21" and treats a missing age as 0, Rule Cascade does neither. In a rule that is handled by a guard, so that a missing age is reported by its own required rule:

when: { op: eq, args: [ { op: typeOf, args: [ { var: data.age } ] }, number ] }

2. Importing presence tests

{ "if": [
  { "missing": [ "firstName", "lastName" ] }, "incomplete",
  { "!": { "var": "termsAccepted" } }, "terms",
  "ok"
] }

missing is the condition of if, so it converts exactly: a property is missing when it is null (or absent) or "". The chain becomes nested ifs.

op: if
args:
  - op: or
    args:
      - { op: in, args: [ { var: data.firstName }, { op: list, args: [ null, "" ] } ] }
      - { op: in, args: [ { var: data.lastName }, { op: list, args: [ null, "" ] } ] }
  - incomplete
  - { op: if, args: [ { op: not, args: [ { var: data.termsAccepted } ] }, terms, ok ] }

warning: $.if[2].!: JSON Logic accepts any value as a condition (null, false, 0, "" and [] count as
false). Rule Cascade requires a boolean and raises an evaluation error otherwise.
truthiness='expand' (--expand-truthiness) converts the test exactly.

If termsAccepted is always a boolean, the conversion is finished. If the form leaves it out until the box is ticked, not(null) is an evaluation error where JSON Logic answered "terms". With --expand-truthiness there is no warning and the last branch reads:

- op: if
  args:
    - { op: in, args: [ { var: data.termsAccepted }, { op: list, args: [ null, false, 0, "", { op: list, args: [] } ] } ] }
    - terms
    - ok

A related rule is refused, and the message says what to write instead:

$ echo '{"or": [{"var": "nickname"}, "anonymous"]}' | python tools/rulecheck.py jsonlogic import -
error: cannot convert: 1 unsupported construct(s)
  $.or[1]: or returns one of its operands in JSON Logic, here a string; Rule Cascade's or takes and
  returns booleans. For a fallback value use var with a default

3. Exporting a rule about a list

"The shares of the splits add up to 100 and each is positive", as a Rule Cascade expression:

op: and
args:
  - { op: eq, args: [ { op: sum, args: [ { var: data.splits }, { var: item.share } ] }, 100 ] }
  - { op: all, args: [ { var: data.splits }, { op: gt, args: [ { var: item.share }, 0 ] } ] }

$ python tools/rulecheck.py jsonlogic export shares.json
warning: $: Rule Cascade raises an evaluation error on operands of the wrong type, and the rule fails
closed. JSON Logic coerces them and returns a value.
warning: $.args[0].args[0]: Rule Cascade computes in decimal (0.1 + 0.2 is 0.3); JSON Logic computes
in binary floating point (0.30000000000000004). Results can differ in the last digits.

{ "and": [
  { "===": [ { "reduce": [ { "var": "splits" },
                           { "+": [ { "var": "accumulator" }, { "var": "current.share" } ] }, 0 ] }, 100 ] },
  { "none": [ { "var": "splits" }, { "!": [ { ">": [ { "var": "share" }, 0 ] } ] } ] }
] }

sum becomes the reduce idiom, and all becomes "none fails" so that an empty list means the same in both. The second warning matters here: shares of 33.4, 33.3 and 33.3 add up to exactly 100 in Rule Cascade and to 99.99999999999999 in json-logic-js.

An expression that uses what JSON Logic lacks is refused, with every reason:

$ python tools/rulecheck.py jsonlogic export swift.json
error: cannot convert: 2 unsupported construct(s)
  $.args[0].args[0]: empty: JSON Logic cannot tell an empty object from one with members
  $.args[1]: matches: JSON Logic has no pattern matching

Rendered from docs/json-logic.md in the repository. Edit it there.