JSON-e

JSON-e is a data-structure parameterization system for embedding context in JSON objects.

The central idea is to treat a data structure as a "template" and render it, using another data structure as "context", to produce an output data structure.

There are countless libraries to do this with strings, such as mustache. What makes JSON-e unique is that it operates on data structures, not on their textual representation. This allows input to be written in a number of formats (JSON, YAML, etc.) or even generated dynamically. It also means that the output cannot be "invalid", even when including large chunks of contextual data.

JSON-e is also designed to be safe for use on untrusted data. It never uses eval or any other function that might result in arbitrary code execution. It also disallows unbounded iteration, so any JSON-e rendering operation will finish in finite time.

Using JSON-e

An application of JSON-e typically allows the user to specify the template, and defines the context with which that template will be rendered as well as how the output will be interpreted. For example, an application that allows customized responses to chat messages might provide context {"message": .., "sender": ..} and expect an object of the form {"reply": ..} as a result.

JSON-e is intended for cross-platform usage, and has native implementations in several languages.

JavaScript

The JS module is installed into a Node project with

npm install --save json-e
yarn add json-e

The module exposes following interface:

import jsone from 'json-e';

var template = {a: {$eval: "foo.bar"}};
var context = {foo: {bar: "zoo"}};
console.log(jsone(template, context));
// -> { a: 'zoo' }

Note that the context can contain functions, and those functions can be called from the template:

var template = {$eval: "foo(1)"};
var context = {"foo": function(x) { return x + 2; }};
console.log(jsone(template, context));  // -> 3

NOTE: Context functions are called synchronously. Any complex asynchronous operations should be handled before rendering the template.

NOTE: If the template is untrusted, it can pass arbitrary data to functions in the context, which must guard against such behavior.

Browser

JSON-e has a single-file, browser-compatible implementation in dist/index.js in the NPM release. This file can be used directly in a browser to add JSON-e functionality.

JSON-e can be used from a CDN with

<script
  type="text/javascript"
  src="https://cdn.jsdelivr.net/npm/json-e">
</script>

TypeScript

The JS module is installed with either of

npm install --save json-e
yarn add json-e

Note: Type definitions are included with this package, so there's no need of seperate @types/.. installation.

As 'json-e' is a CommonJS module, the package must be imported like this (more..) for type definitions to work properly:

const jsone = require('json-e');

var template = {a: {$eval: "foo.bar"}};
var context = {foo: {bar: "zoo"}};
console.log(jsone(template, context));
// -> { a: 'zoo' }

Python

The Python distribution is installed with

pip install json-e

The distribution exposes a render function:

import jsone

template = {"a": {"$eval": "foo.bar"}}
context = {"foo": {"bar": "zoo"}}
print(jsone.render(template, context))  # -> {"a": "zoo"}

and also allows custom functions in the context:

template = {"$eval": "foo(1)"}
context = {"foo": lambda x: x + 2}
print(jsone.render(template, context))  # -> 3

Go (golang)

The golang package for json-e exposes a Render function:

import (
  "fmt"
  jsone "github.com/json-e/json-e/v4"
)

// Template must be given using types:
//   map[string]interface{}, []interface{}, float64, string, bool, nil
// The same types that json.Unmarshal() will create when targeting an interface{}
var template = map[string]interface{}{
  "result": map[string]interface{}{
    "$eval": "f() + 5",
  },
}
// Context can be JSON types just like template, but may also contain functions
// these can JSON types as arguments, and return a value and optionally an error.
var context = map[string]interface{}{
  "f": jsone.WrapFunction(func() float64 { return 37 }),
}

func main() {
  value, _ := jsone.Render(template, context)
  fmt.Printf("%#v\n", value)
}

Rust

The Rust crate exposes a render function which takes the template and context as serde_json Value objects, and returns an object of the same type.

use serde_json::json;

fn main() {
    println!("result: {:?}", json_e::render(
        json!({$eval: "a + b"}),
        json!({a: 10, b: 20})));
}

See docs.rs for the full API docs.

.NET

See json-everything for a .NET implementation of JSON-e.

Third-Party Integrations

rjsone

You can use the 3rd party package rjsone to template JSON-e from the command line, passing templates/contexts as files or arguments and using stdout for the result.

Bazel

You can use 3rd party Bazel rule to invoke rjsone (see above) from Bazel build files.

Terraform

The jsone Terraform provider allows use of JSON-e for templating objects within Terraform.

Language Reference

The following sections describe the JSON-e language.

The examples here are given in YAML for ease of reading. Of course, the rendering operation takes place on the parsed data, so the input format is irrelevant to its operation.

Rendering

A JSON-e template is rendered with a context to produce a result. The template, context, and result are all data structures containing strings, numbers, true/false, null, objects, and arrays -- the type of data structure you get from parsing JSON.

The context is an object, giving values for variables at the top level of the template.

Variables and Scope

Variables are defined in a set of nested scopes. When an expression references a variable, evaluation looks for a variable of that name in all scopes, from innermost to outermost, and uses the first that it finds.

The outermost scope are the built-ins. The context passed to the render call is used as the next scope, an thus can override built-in variables. Some operators, such as $let, allow the template to define additional scopes during rendering.

Variables can contain functions defined by the caller. While these functions can be used during rendering, it is an error for them to appear in the result.

Simple Usage

All JSON-e directives involve the $ character, so a template without any directives is rendered unchanged:

template: {key: [1,2,{key2: 'val', key3: 1}, true], f: false}
context:  {}
result:   {key: [1,2,{key2: 'val', key3: 1}, true], f: false}

String Interpolation

The simplest form of substitution occurs within strings, using ${..}:

template: {message: 'hello ${key}', 'k=${num}': true}
context:  {key: 'world', num: 1}
result:   {message: 'hello world', 'k=1': true}

The bit inside the ${..} is an expression, and must evaluate to something that interpolates obviously into a string (a string, number, or boolean). If it is null, then the expression interpolates into an empty string.

Values interpolate as their JSON literal values:

template: ["number: ${num}", "booleans: ${t} ${f}", "null: ${nil}"]
context: {num: 3, t: true, f: false, nil: null}
result: ["number: 3", "booleans: true false", "null: "]

Note that object keys can be interpolated, too:

template: {"tc_${name}": "${value}"}
context: {name: 'foo', value: 'bar'}
result: {"tc_foo": "bar"}

The string ${ can be escaped as $${:

template: {"literal:$${name}": "literal"}
context: {name: 'foo'}
result: {"literal:${name}": "literal"}

Operators

JSON-e defines a bunch of operators. Each is represented as an object with a property beginning with $. This object can be buried deeply within the template. Some operators take additional arguments as properties of the same object.

Truthiness

Many values can be evaluated in context where booleans are required, not just booleans themselves. JSON-e defines the following values as false. Anything else will be true.

template: {$if: 'a || b || c || d || e || f', then: "uh oh", else: "falsy" }
context: {a: null, b: [], c: {}, d: "", e: 0, f: false}
result: "falsy"

`$eval`

The $eval operator evaluates the given expression and is replaced with the result of that evaluation. Unlike with string interpolation, the result need not be a string, but can be an arbitrary data structure.

template: {config: {$eval: 'settings.staging'}}
context:
  settings:
    staging:
      transactionBackend: mock
    production:
      transactionBackend: customerdb
result:
  {config: {transactionBackend: 'mock'}}

The expression syntax is described in more detail below.

Note that $eval's value must be a string. "Metaprogramming" by providing a calculated value to eval is not allowed. For example, {$eval: {$eval: "${var1} + ${var2}"}} is not valid JSON-e.

`$json`

The $json operator formats the given value as JSON with sorted keys. It does not evaluate the value (use $eval for that). While this can be useful in some cases, it is an unusual case to include a JSON string in a larger data structure.

Parsing the result of this operator with any compliant JSON parser will give the same results. However, the encoding may differ between implementations of JSON-e. For example, numeric representations or string escapes may differ between implementations.

template: {$json: [a, b, {$eval: 'a+b'}, 4]}
context:  {a: 1, b: 2}
result:   '["a","b",3,4]'

`$if` - `then` - `else`

The $if operator supports conditionals. It evaluates the given value, and replaces itself with the then or else properties. If either property is omitted, then the expression is omitted from the parent object.

template: {key: {$if: 'cond', then: 1}, k2: 3}
context:  {cond: true}
result:   {key: 1, k2: 3}

template: {$if: 'x > 5', then: 1, else: -1}
context:  {x: 10}
result:   1

template: [1, {$if: 'cond', else: 2}, 3]
context: {cond: false}
result: [1,2,3]

template: {key: {$if: 'cond', then: 2}, other: 3}
context: {cond: false}
result: {other: 3}

`$flatten`

The $flatten operator flattens an array of arrays into one array.

template: {$flatten: [[1, 2], [3, 4], [5]]}
context:  {}
result:   [1, 2, 3, 4, 5]

`$flattenDeep`

The $flattenDeep operator deeply flattens an array of arrays into one array.

template: {$flattenDeep: [[1, [2, [3]]]]}
context:  {}
result:   [1, 2, 3]

`$fromNow`

The $fromNow operator is a shorthand for the built-in function fromNow. It creates a JSON (ISO 8601) datestamp for a time relative to the current time (see the now builtin, below) or, if from is given, relative to that time.

The offset is specified by a sequence of number/unit pairs in a string. Whitespace is ignored, but the units must be given in ordre from largest to smallest. To produce a time in the past, prefix the string with -. A + prefix is allowed as a redundant way to specify a time in the future.

template: {$fromNow: '2 days 1 hour'}
context:  {}
result:   '2017-01-21T17:27:20.974Z'

template: {$fromNow: '1 hour', from: '2017-01-19T16:27:20.974Z'}
context:  {}
result:   '2017-01-19T17:27:20.974Z'

The available units, including useful shorthands, are:

years,    year,   yr,   y
months,   month,  mo
weeks,    week,   wk,   w
days,     day,          d
hours,    hour,   hr,   h
minutes,  minute, min,  m
seconds,  second, sec,  s

`$let`

The $let operator evaluates an expression using a context amended with the given values. It is analogous to the Haskell where clause.

template: {$let: {ts: 100, foo: 200},
           in: [{$eval: "ts+foo"}, {$eval: "ts-foo"}, {$eval: "ts*foo"}]}
context: {}
result: [300, -100, 20000]

The $let operator here added the ts and foo variables to the scope of the context and accordingly evaluated the in clause using those variables to return the correct result.

An expression like {$let: {$eval: "extraVariables"}, in : ..} is supported. As long as the value of $let evaluates to an object with valid key(s), the values of which are evaluated.

template: {$let: {$if: something == 3, then: {a: 10, b: 10}, else: {a: 20, b: 10}},
          in: {$eval: 'a + b'}}
context:  {'something': 3}
result:   20

template: {$let: {"b": {$eval: "a + 10"}},
          in: {$eval: "a + b"}}
context:  {a: 5}
result:   20

template: {$let: {"first_${name}": 1, "second_${name}": 2},
          in: {$eval: "first_prize + second_prize"}}
context:  {name: "prize"}
result:   3

`$map`

The $map operator evaluates an expression for each value of the given array or object, constructing the result as an array or object of the evaluated values.

Over Arrays

When given an array, $map always returns an array.

template:
  $map: [2, 4, 6]
  each(x): {$eval: 'x + a'}
context:  {a: 1}
result:   [3, 5, 7]

The each function can define two variables, in which case the second is the 0-based index of the element.

template:
  $map: [2, 4, 6]
  each(x,i): {$eval: 'x + a + i'}
context:  {a: 1}
result:   [3, 6, 9]

Over Objects

When given an object, $map always returns an object. The each function defines variables for the value and key, in that order. It must evaluate to an object for each item. These objects are then merged, with later keys overwriting earlier keys, to produce the final object.

template:
  $map: {a: 1, b: 2, c: 3}
  each(v,k): {'${k}x': {$eval: 'v + 1'}}
context:  {}
result: {ax: 2, bx: 3, cx: 4}

If each is defined to take only one variable, then that variable is an object with properties key and val.

template:
  $map: {a: 1, b: 2, c: 3}
  each(y): {'${y.key}x': {$eval: 'y.val + 1'}}
context:  {}
result: {ax: 2, bx: 3, cx: 4}

`$reduce`

The $reduce operator evaluates an expression with each value of the given array and the result of the prior expression, reducing the array into a single JSON value.

This operation is sometimes called fold, accumulate, aggregate, or inject.

An initial result is passed as the accumulator for the first evaluation of the expression.

The each function defines the accumulated, or prior result, and the current value. The result of this function will be passed as the accumulated to the next call of each.

template:
  $reduce: [{name: Apple, price: 1}, {name: Orange, price: 0.75}, {name: Pear, price: 1.1}]
  initial: 0
  each(acc, v): {$eval: 'acc + v.price'}
context:  {}
result:   2.85

The each function can define three variables, in which case the third is the 0-based index of the element.

template:
  $reduce: [2, 5, 8]
  initial: 0
  each(acc, v, i): {$eval: 'acc + v * 10 ** i'}
context:  {}
result:   852

`$find`

The $find operator evaluates an expression for each value of the given array. returning the first value for which the expression evaluates to true.

If there are no matches the result is either null or if used within an object or array, omitted from the parent object.

template:
  $find: [2, 4, 6]
  each(x): x == 4
context: {}
result: 4

Using context variables:

template:
  $find: [2, 4, 6]
  each(x): a == x
context: {a: 4}
result: 4

Omitting from parent:

template:
  a: 1
  b:
    $find: [2, 4, 6]
    each(x): b == x
context:
  b: 3
result:
  a: 1

The each function can define two variables, in which case the second is the 0-based index of the element.

template:
  $find: [2, 4, 6]
  each(x,i): i == 2
context: {}
result: 6

`$match`

The $match operator is not dissimilar to pattern matching operators. It gets an object, in which every key is a string expression evaluating to true or false based on the context. Keys are evaluated in lexical order, and the result is an array containing values corresponding to keys that evaluated to true. If there are no matches, the result is an empty array.

template:
  $match: 
    "c > 10": "cherry"
    "b > 10": "banana"
    "a > 10": "apple"
context: {a: 200, b: 3, c: 19}
result: ["apple", "cherry"]

template: {$match: {"x < 10": "tens"}}
context: {x: 10}
result: []

`$switch`

The $switch operator behaves like a combination of the $if and $match operator for more complex boolean logic. It gets an object, in which every key is a string expression(s), where at most one must evaluate to true and the remaining to false based on the context. The result will be the value corresponding to the key that were evaluated to true or optionally the fallback $default value.

If there are no matches, and no $default fallback is provided, the result is either null or if used within an object or array, omitted from the parent object.

template: {$switch: {"x == 10": "ten", "x == 20": "twenty"}}
context: {x: 10}
result: "ten"

template: {$switch: {"x < 10": 1}}
context: {x: 10}
result: null

template: {a: 1, b: {$switch: {"x == 10 || x == 20": 2, "x > 20": 3}}}
context: {x: 10}
result: {a: 1, b: 2}

template: {a: 1, b: {$switch: {"x == 1": 2, "x == 3": 3}}}
context: {x: 2}
result: {a: 1}

template: [1, {$switch: {"x == 2": 2, "x == 10": 3}}]
context: {x: 2}
result: [1, 2]

template: [0, {$switch: {'cond > 3': 2, 'cond == 5': 3}}]
context:  {cond: 3}
result:   [0]

template: [0, {$switch: {'cond > 3': 2, 'cond == 5': 3, $default: 4}}]
context:  {cond: 1}
result:   [4]

`$merge`

The $merge operator merges an array of objects, returning a single object that combines all of the objects in the array, where the right-side objects overwrite the values of the left-side ones.

template: {$merge: [{a: 1, b: 1}, {b: 2, c: 3}, {d: 4}]}
context:  {}
result:   {a: 1, b: 2, c: 3, d: 4}

`$mergeDeep`

The $mergeDeep operator is like $merge, but it recurses into objects to combine their contents property by property. Arrays are concatenated.

template:
  $mergeDeep:
    - task:
        payload:
          command: [a, b]
    - task:
        extra:
          foo: bar
    - task:
        payload:
          command: [c]
context:  {}
result:
  task:
    extra:
      foo: bar
    payload:
      command: [a, b, c]

`$sort`

The $sort operator sorts the given array. It takes a by(var) property which should evaluate to a comparable value for each element. The by(var) property defaults to the identity function.

The values sorted must all be of the same type, and either a number or a string.

template:
  $sort: [{a: 2}, {a: 1, b: []}, {a: 3}]
  by(x): 'x.a'
context:  {}
result:   [{a: 1, b: []}, {a: 2}, {a: 3}]

The sort is stable:

template:
  $sort: ["aa", "dd", "ac", "ba", "ab"]
  by(x): 'x[0]'
context:  {}
# stable: all "a" strings remain in the same order relative to one another.
result:   ["aa", "ac", "ab", "ba", "dd"]

`$reverse`

The $reverse operator simply reverses the given array.

template: {$reverse: [3, 4, 1, 2]}
context:  {}
result:   [2, 1, 4, 3]

Escaping operators

All property names starting with $ are reserved for JSON-e. You can use $$ to escape such properties:

template: {$$reverse: [3, 2, {$$eval: '2 - 1'}, 0]}
context:  {}
result:   {$reverse: [3, 2, {$eval: '2 - 1'}, 0]}

Expressions

Expression are given in a simple Python- or JavaScript-like expression language. Its data types are limited to JSON types plus function objects.

Literals

Literals are similar to those for JSON Numeric literals, but only accept integer and decimal notation.

template:
  - {$eval: "1.3"}
context: {}
result:
  - 1.3

Strings do not support any kind of escaping, but can be enclosed in either " or in '. To avoid confusion when writing JSON-e expressions in YAML or JSON documents, remember that JSON-e operates on the data structure that results after YAML or JSON parsing is complete.

template:
  - {$eval: "'abc'"}
  - {$eval: '"abc"'}
context: {}
result:
  - "abc"
  - "abc"

Array and object literals also look much like JSON, with bare identifiers allowed as keys like in Javascript:

template:
  - {$eval: '[1, 2, "three"]'}
  - {$eval: '{foo: 1, "bar": 2}'}
context: {}
result:
  - [1, 2, "three"]
  - {"foo": 1, "bar": 2}

Context References

Bare identifiers refer to items from the context or to built-ins (described below).

template: {$eval: '[x, z, x+z]'}
context: {x: 'quick', z: 'sort'}
result: ['quick', 'sort', 'quicksort']

Valid identifiers for context references follow the requirements of many programming languages: identifiers may only contain letters, underscores, and numbers, but may not start with a number. This does imply that the context object may only have keys that meet these requirements.

Arithmetic Operations

The usual arithmetic operators are all defined, with typical associativity and precedence:

template:
  - {$eval: 'x + z'}
  - {$eval: 's + t'}
  - {$eval: 'z - x'}
  - {$eval: 'x * z'}
  - {$eval: 'z / x'}
  - {$eval: 'z ** 2'}
  - {$eval: '(z / x) ** 2'}
context: {x: 10, z: 20, s: "face", t: "plant"}
result:
  - 30
  - "faceplant"
  - 10
  - 200
  - 2
  - 400
  - 4

Note that strings can be concatenated with +, but none of the other operators apply.

Comparison Operations

Comparisons work as expected. Equality is "deep" in the sense of doing comparisons of the contents of data structures.

template:
  - {$eval: 'x < z'}
  - {$eval: 'x <= z'}
  - {$eval: 'x > z'}
  - {$eval: 'x >= z'}
  - {$eval: 'deep == [1, [3, {a: 5}]]'}
  - {$eval: 'deep != [1, [3, {a: 5}]]'}
context: {x: -10, z: 10, deep: [1, [3, {a: 5}]]}
result: [true, true, false, false, true, false]

Boolean Operations

Boolean operations use C- and Javascript-style symbols ||, &&, and !:

template: {$eval: '!(false || false) && true'}
context: {}
result: true

Json-e supports short-circuit evaluation, so if in || left operand is true returning value will be true no matter what right operand is:

template: {$eval: "true || b"}
context: {}
result: true

And if in && left operand is false returning value will be false no matter what right operand is:

template: {$eval: "false && b"}
context: {}
result: false

Object Property Access

Like Javascript, object properties can be accessed either with array-index syntax or with dot syntax. Unlike Javascript, obj.prop is an error if obj does not have prop, while obj['prop'] will evaluate to null.

template: {$eval: 'v.a + v["b"]'}
context: {v: {a: 'apple', b: 'banana', c: 'carrot'}}
result: 'applebanana'

Note that the object can be a literal expression:

template: {$eval: '{ENOMEM:"Out of memory", ENOCPU:"Out of CPUs"}[msgid]'}
context: {msgid: ENOMEM}
result: 'Out of memory'

When using the dot-syntax, e.g. .prop, identifiers may only contain letters, underscores, and numbers, but may not start with a number (just like for context references). While the context object may only have keys that meet these requirements, nested objects may have keys in any format. Keys that are not in the identifier format must be accessed using the bracket-name syntax, e.g. ['my-prop'].

Indexing and Slicing

Strings and arrays can be indexed and sliced using a Python-like indexing scheme. Negative indexes are counted from the end of the value. Slices are treated as "half-open", meaning that the result contains the first index and does not contain the second index. A "backward" slice with the start index greater than the end index is treated as empty.

Strings are treated as a sequence of Unicode codepoints.

template:
  - {$eval: '[array[1], string[1]]'}
  - {$eval: '[array[1:4], string[1:4]]'}
  - {$eval: '[array[2:], string[2:]]'}
  - {$eval: '[array[:2], string[:2]]'}
  - {$eval: '[array[4:2], string[4:2]]'}
  - {$eval: '[array[-2], string[-2]]'}
  - {$eval: '[array[-2:], string[-2:]]'}
  - {$eval: '[array[:-3], string[:-3]]'}
context: {array: ['a', 'b', '☪', 'd', 'e'], string: 'ab☪de'}
result:
  - ['b', 'b']
  - [['b', '☪', 'd'], 'b☪d']
  - [['☪', 'd', 'e'], '☪de']
  - [['a', 'b'], 'ab']
  - [[], '']
  - ['d', 'd']
  - [['d', 'e'], 'de']
  - [['a', 'b'], 'ab']

Containment Operation

The in keyword can be used to check for containment: a property in an object, an element in an array, or a substring in a string.

template:
  - {$eval: '"foo" in {foo: 1, bar: 2}'}
  - {$eval: '"foo" in ["foo", "bar"]'}
  - {$eval: '"foo" in "foobar"'}
context: {}
result: [true, true, true]

Function Invocation

Function calls are made with the usual fn(arg1, arg2) syntax. Functions are not JSON data, so they cannot be created in JSON-e, but they can be provided as built-ins or supplied in the context and called from JSON-e.

Built-In Functions and Variables

The expression language provides a laundry-list of built-in functions/variables. Library users can easily add additional functions/variables, or override the built-ins, as part of the context.

Time

The built-in context value now is set to the current time at the start of evaluation of the template, and used as the default "from" value for $fromNow and the built-in fromNow().

template:
  - {$eval: 'now'}
  - {$eval: 'fromNow("1 minute")'}
  - {$eval: 'fromNow("1 minute", "2017-01-19T16:27:20.974Z")'}
context: {}
result:
  - '2017-01-19T16:27:20.974Z'
  - '2017-01-19T16:28:20.974Z'
  - '2017-01-19T16:28:20.974Z'

Math

template:
  # the smallest of the arguments
  - {$eval: 'min(1, 3, 5)'}
  # the largest of the arguments
  - {$eval: 'max(2, 4, 6)'}
  # mathematical functions
  - {$eval: 'sqrt(16)'}
  - {$eval: 'ceil(0.3)'}
  - {$eval: 'floor(0.3)'}
  - {$eval: 'abs(-0.3)'}
context: {}
result:
  - 1
  - 6
  - 4
  - 1
  - 0
  - 0.3

Strings

template:
  # convert string case
  - {$eval: 'lowercase("Fools!")'}
  - {$eval: 'uppercase("Fools!")'}
  # convert string, number, or boolean to string
  # (arrays and objects cannot be converted to string)
  - {$eval: 'str(130)'}
  # convert a string to a number (string is required)
  - {$eval: 'number("310")'}
  # strip whitespace from left, right, or both ends of a string
  - {$eval: 'lstrip("  room  ")'}
  - {$eval: 'rstrip("  room  ")'}
  - {$eval: 'strip("  room  ")'}
  - {$eval: 'split("left:right", ":")'}
context: {}
result:
  - "fools!"
  - "FOOLS!"
  - "130"
  - 310
  - "room  "
  - "  room"
  - room
  - [left, right]

Arrays

template:
  - {$eval: 'join(["carpe", "diem"], " ")'}
  - {$eval: 'join([1, 3], 2)'}
context: {}
result:
  - carpe diem
  - '123'

Context

The defined(varname) built-in determines if the named variable is defined in the current context. The current context includes any variables defined or redefined by $let or similar operators. Note that the name must be given as a string.

template: {$if: 'defined("x")', then: {$eval: 'x'}, else: 20}
context: {y: 10}
result: 20

Type

The typeof() built-in returns the type of an object. Its behavior around null is reminiscent of JavaScript.

template:
 - "${typeof('abc')}"
 - "${typeof(42)}"
 - "${typeof(42.0)}"
 - "${typeof(true)}"
 - "${typeof([])}"
 - "${typeof({})}"
 - "${typeof(typeof)}"
 - {$eval: "typeof(null)"}
 - "${typeof(null)}"
context: {}
result:
 - string
 - number
 - number
 - boolean
 - array
 - object
 - function
 - 'null'
 - 'null'    # .. which interpolates to an empty string

Length

The len() built-in returns the length of a string or array.

template: {$eval: 'len([1, 2, 3])'}
context: {}
result: 3

Range

The range() built-in generates an array based on the following inputs:

start - An integer specifying the lower bound of the range (inclusive). This can be negative, in which case the generated array of integers will start with this negative value (inclusive).
end - An integer specifying the upper bound of the range (exclusive). This can be negative, in which case the generated array of integers will end with this negative value (exclusive).
step - Optional. An integer specifying a step to apply to each value within the range. If not specified, defaults to 1. Can be negative, but cannot be zero.

The contents of a range r are determined by the following formula:

IF step > 0 THEN

  i = start
  WHILE i < end:
    r(i) = i
    i = i + step
  END WHILE

ELSE if step < 0 THEN

  i = start
  WHILE i > end:
    r(i) = i
    i = i + step
  END WHILE

END IF

Notably, the resulting range will be empty if start >= end and step is positive or if start <= end and step is negative.

template:
  $map: {$eval: 'range(1, 5)'}
  each(x): {$eval: 'x'}
context:  {}
result:   [1, 2, 3, 4]

Playground

This page executes JSON-e live in your browser.

template:
  message:
    $eval: payload.message_body
context:
  payload:
    message_body: "Hello, world!"
result:
  message: Hello, world!