# JSON Dotted Key Transformer (mmjsontransform)

Module Name: | mmjsontransform
Author: | rsyslog project
Available since: | 8.2410.0

Note

`mmjsontransform` is a fresh module. Parameter names and behavior may still change as real-world feedback arrives, so expect possible breaking adjustments in upcoming releases.

# Purpose

`mmjsontransform` restructures JSON properties whose names contain dotted segments. The action reads a JSON object from the configured input property and stores the transformed tree under a dedicated output property. By default the module expands dotted keys into nested containers (`unflatten` mode) so pipelines that consume `option.jsonfTree` data can normalize payloads inline. When `mode="flatten"` is selected, the action collapses nested objects back into dotted keys.

# Failure conditions

`mmjsontransform` aborts the action when any of the following occur:

- The input property does not resolve to a JSON object.

- The output property already exists on the message.

- Rewriting a key would overwrite an existing incompatible value (for example, `{"a": 1}` combined with `{"a.b": 2}`).

# Notable Features

- Transformation modes — bidirectional conversion between dotted keys and nested containers.

- Conflict handling — detailed conflict reporting to locate incompatible payloads quickly.

# Configuration Parameters

Note

Parameter names are case-insensitive. For readability, camelCase is recommended.

## Action Parameters

Parameter | Summary
--- | ---
input | Names the JSON property that provides the object to transform.
output | Sets the destination property that receives the rewritten JSON tree.
mode | Chooses whether dotted keys are expanded or flattened during processing.

# Transformation modes

`mmjsontransform` supports two modes controlled by the mode parameter. Both modes rewrite the entire input object before assigning it to the configured output property.

## Unflatten dotted keys

`mode="unflatten"` (the default) expands dotted keys into nested containers. For example `{"a.b": 1, "a.c": 2}` becomes `{"a": {"b": 1, "c": 2}}`. When the module encounters a dotted path that points to an existing non-object value, it stops processing, leaves the output unset, and reports the conflicting path.

## Flatten nested containers

`mode="flatten"` performs the reverse operation. Nested objects become dotted key paths (`{"nested": {"value": 1}}` is rewritten to `{"nested.value": 1}`), while arrays are preserved with their elements recursively flattened. If flattening would overwrite an existing scalar with a different value, the action fails and reports the mismatch.

# Conflict handling

The module tracks the full dotted path responsible for a hierarchy conflict and logs a user-facing error when a mismatch occurs. Review the reported path to identify which input property must be renamed or preprocessed before retrying the transformation.

# Examples

## Normalize and persist dotted JSON

The following snippet receives JSON payloads, normalizes dotted keys into nested objects, and writes both the structured tree and a flattened representation to `/tmp/out.json`:

    module(load="mmjsontransform")
    module(load="imtcp")

    input(type="imtcp" port="10514" ruleset="process-json")

    ruleset(name="process-json") {
        action(type="mmjsontransform" input="$!raw" output="$!normalized")
        action(type="mmjsontransform" mode="flatten"
               input="$!normalized" output="$!normalized_flat")
        action(type="omfile" file="/tmp/out.json"
               template="json-template")
    }

    template(name="json-template" type="string"
             string="%$!normalized%\n%$!normalized_flat%\n")

# Troubleshooting

When a hierarchy conflict occurs (for example, `mode="unflatten"` sees `"a": "value"` and `"a.b": 1`), `mmjsontransform` logs an error that includes the conflicting path. Inspect the reported path to determine which input property needs to be renamed or moved before retrying the transformation.

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project

© 2008–2025 Rainer Gerhards and others. Licensed under the Apache License 2.0.