transon

Homogeneous JSON template engine. transon creates JSON out of template and JSON input.

                    ┌─────────────────┐
                    │  JSON Template  │
                    └────────┬────────┘
                             │
┌──────────────┐    ┌────────▼────────┐    ┌───────────────┐
│  JSON Input  ├────►     transon     ├────►  JSON Output  │
└──────────────┘    └─────────────────┘    └───────────────┘

Documentation and playground: https://transon-org.github.io/

transon is a powerful and flexible JSON template engine that enables developers to transform JSON data using a customizable set of rules. With transon, you can generate dynamic templates, manipulate JSON data, and produce new JSON structures that meet your specific requirements.

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.

Installation

transon can be installed using pip, the Python package manager. Simply run the following command:

pip install transon

Development

Requires Python 3.9+ and uv.

uv sync --dev
uv run pytest .

Inspired by

• XSLT
• JsonLogic

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:

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.