transon

Homogeneous JSON template engine — the template is itself plain JSON.

What is transon?

transon turns one JSON document into another. You describe the shape of the output as a template — itself plain JSON — and put small placeholder rules (objects marked with "$") where data should flow in. No glue code to write, no separate template language to learn.

A template, some input, and what comes out — pull one field from every record:

Template:

{"$": "map", "item": {"$": "attr", "name": "email"}}

Input:

[
  {"name": "Ada", "email": "ada@example.com"},
  {"name": "Alan", "email": "alan@example.com"},
  {"name": "Grace", "email": "grace@example.com"}
]

Output:

["ada@example.com", "alan@example.com", "grace@example.com"]

Try it live in the documentation & playground.

Why transon?

• Templates are data. Store them in a database, generate them from code, review them as diffs, validate them before running — they are plain JSON values, not strings in a DSL.
• A few rules, endlessly combined. Iteration, lookups, conditionals, formatting — even arithmetic — are the same small building blocks, nested inside each other.
• Extend it in Python. Register your own rules, operators, and functions when the built-ins aren't enough.

Inspired by XSLT (declarative, tree-to-tree transformation) and JsonLogic (logic expressed as data).

Installation

pip install transon

Your first transform:

from transon import Transformer

template = {"items": {"$": "map", "item": {"$": "item"}}}
Transformer(template).transform(["a", "b"])  # => {"items": ["a", "b"]}

Highlights

Things you'll appreciate once you start writing real templates:

• Missing data just disappears. An absent field produces "no value" rather than an error; containers skip it instead of emitting null holes; and any lookup can declare a default.
• Catch template mistakes before running anything. Opt-in static validation checks a template's structure with no input data at all.
• Errors that point at the template. A malformed template and data that doesn't fit are distinct errors, and both name the exact template path that failed (at template → …).
• Emit anything — even data that looks like a rule. Literal $ keys are expressible, and the marker itself is configurable if $ collides with your data.
• The docs travel with the package. An installed transon serves its own Language Reference, editor metadata, and generated docs — offline, version-matched.

Comparison

JSON transformation is a crowded space. transon's bet is that templates are themselves pure JSON — storable, generatable, diff-able, and extensible with your own rules — traded against the terseness of a string DSL. Pick the tool that fits the job:

Tool	Template / language	Extensible	Deps & runtime	Best when
transon	pure JSON tree	custom rules, operators, functions	none (Python stdlib)	templates must be stored / generated / validated as JSON, with domain-specific rules, in Python
JSONata	string expression DSL	limited	JS library	concise queries & expressions over JSON in JavaScript
jq	string filter language	limited	native binary	CLI piping and ad-hoc filtering in the shell
JSLT	string DSL (jq-like)	user functions	JVM	compact JSON→JSON on the JVM
Jolt	JSON spec	limited	JVM	declarative structural reshaping on the JVM
JsonLogic	JSON logic tree	limited	small libs (many languages)	portable business/boolean rules shared across services
JSON-e	JSON template	limited	JS / Python	parameterising JSON config with interpolation
Jsonnet	full templating language	yes	native binary	generating large config (e.g. Kubernetes) from a real language
json-templates	JSON with {{placeholders}}	no	tiny JS library	simple value substitution into a JSON skeleton

Where transon is not the best pick (worth being honest about):

• Expression-heavy transforms read far more concisely in a string DSL like JSONata or jq — transon spells (a + b) * c as a nested rule tree.
• Maturity & ecosystem: jq and JSONata are battle-tested with large communities; transon is young and Python-only.

The trade-off, concretely

The same transform — multiply each order's qty by its price — over input {"orders": [{"qty": 2, "price": 3}, {"qty": 5, "price": 7}]}:

JSONata — a terse string expression:

orders.(qty * price)

transon — pure JSON, composable rules:

{
  "$": "chain",
  "funcs": [
    {"$": "attr", "name": "orders"},
    {
      "$": "map",
      "item": {
        "$": "expr",
        "op": "mul",
        "values": [
          {"$": "attr", "name": "qty"},
          {"$": "attr", "name": "price"}
        ]
      }
    }
  ]
}

Both yield [6, 35]. JSONata wins on brevity; transon wins when the template itself must be data — stored in a database, generated by another program, reviewed as a diff, checked with Transformer.validate(), or extended with your own rules.

Development Principles

transon was built with a set of key development principles in mind, including:

• Flexibility and Extensibility: transon is designed to be highly flexible and extensible, allowing you to add new rules and types of placeholders to suit your unique needs.
• Valid JSON Structure: transon templates are defined as valid JSON structures, making them easy to work with and compatible with a wide range of tools and applications.
• Composable Rules: transon rules are highly composable, allowing you to define complex behavior patterns using a combination of nested rules. For example, arithmetic expressions can be defined with nested rules, where each rule represents a specific operation. This approach eliminates the need for a domain-specific language (DSL) for arithmetic expressions.
• Marker-Based Templates: The most important aspect of a transon template is the use of the $ marker. This marker is a special key within the JSON structure that distinguishes it from other types of JSON data. By default, the $ key is used as the marker, but you can change it to any other value you prefer.

By using a marker-based approach, transon ensures that templates are easy to work with and can be easily distinguished from other types of JSON data. This makes it simple to generate dynamic templates, manipulate JSON data, and produce new JSON structures that meet your specific requirements. Additionally, the composable rules approach allows for advanced behavior patterns that can be defined using a combination of nested rules, making transon highly flexible and extensible.

Development

Requires Python 3.9+ and uv.

uv sync --dev
uv run pytest .