Introduction

Transformers are JSON value spec templates.

It is used to transform multiple inputs (by spec) to a result object.

The most basic input to a transformer is $. All references to it can use JsonPath syntax.

Packages

Language	Name	Description	License	Status
Java	ai.bizone.json-transform	Java library for transforming JSON objects	Apache License 2.0
JavaScript	@bizone-ai/json-transform	JSON transformers JavaScript implementation	MIT
JavaScript	@bizone-ai/json-transform-utils	Core types and utilities for handling JSON transformers	MIT
JavaScript	@bizone-ai/monaco-json-transform	Monaco editor extension for JSON transformers	MIT

Macros (or context)

Starts with #, inside transformers:

• #now - ISO 8601 Timestamp as string (e.g. "2025-01-01T12:00:59.123Z")
• #uuid - Random UUID as string (with hyphens) (e.g. "08f33921-12f9-44fe-bb89-0a036b8bd9b1")
• #null - Has the value null useful when used together with spread to remove a value

note

You can add additional context by supplying a Map<String, Object> to the transform function (see Function Context).

Inline Functions

Inline functions can be used as prefix to values (referenced by strings):

• Functions are prefixes for a path or a value in the format $$func:{value}
  • ending with just : will result with empty string as input "" (omitting : will result in null)
  • Functions can be piped to other functions as values
• Functions may have arguments
  • Specified after the function name between parenthesis (e.g. $$func(arg1,arg2):{value})
  • Arguments can be optional/required (parenthesis can be omitted if no arguments at all)
  • All arguments can be paths to other variables (e.g. $$func($.somepath,#current):$.somevalue)
  • All arguments can be quoted with (') single quote, escape it by prefixing it with a backslash \ (e.g. $$wrap('don\'t '):{value})
    • If you use ' inside an argument, you must quote it and escape its usages.
    • Quoting requires escaping, so remember to escape the backslash twice in JSON strings (e.g. "$$wrap('don\\'t '):{value}").
  • enum argument values are case-insensitive
  • Specifying string/enum arguments can be done without quotes
    • enum type values are detected even with spaces around them (trimmed)
    • However, string type values will not be trimmed (e.g. arg2 of $$func(1, hi):{value} will be processed as " hi"). To allow spaces between this kind of arguments, the values needs to be quoted (e.g. $$func(1, 'hi'):{value})

warning

Although JsonPath functions (available in the Java implementation) might work, it is discouraged to use them as it is not supported in other platform implementations and might be removed in future versions (use inline json transformers functions instead where needed).

Object functions

There are special functions that support more complex arguments.

• These functions are defined by putting an Object value with a "function key" (starts with "$$").
• The input argument is the value of the function key. The rest of the arguments may be supplied as other keys in the same object.

Context

Object functions also support nested function context

Examples

Input

Definition

Output

{ "hello": "world" }

"$.hello"

"world"

{ "hello": "world" }

{ "x": "$.hello" }

{ "x": "world"}

{ "d": 13.333 }

"$$long:$.d"

13

{ "a": [ "b", { "c": "d" } ] }

"$.a[1].c"

"d"

[ {"a": 1}, {"a": 2} ]

"$.*.a"

[1, 2]

"text"

"$$join(s):$$split(x):$"

"test"

{ "x": "text"}

"$$wrap(>):$$substring(1,3):$.x"

">ex"