Transformer Rule Engine

Declaratively reshape JSON inside Token Tamer by composing JSONPath matchers with JSON Patch outputs. This guide captures the user-facing rule syntax, execution order, and guardrails reflected in the npm package and the built-in Tamed Payload panel.

How the transformer flows

1. Review the payload

Inspect the JSON tree, decide what should stay, move, or vanish, and sketch the rule sequence. You can type directly in the builder or paste JSON exported from scripts, agents, or an earlier Token Tamer session.

2. Compose rules

Each rule targets part of the document and emits a patch. Replace can pull values from elsewhere, move shifts data between branches, and rename swaps key labels without copying payloads. Rules run in order, so earlier work feeds later matchers.

3. Inspect & export

Compare originals vs. transformed payloads, validate against an optional schema, and download either the JSON or the rule set. Everything runs locally, so you can replay the same rules inside your own codebase with the npm package.

Rule shape

Rules are plain objects. The builder creates them for you, but you can also author them by hand or source them from your own tooling when you use `json-remap-engine` directly.

type Op = "remove" | "replace" | "move" | "rename";

interface Rule {
  id: string;
  matcher: string;      // JSONPath expression -> matching nodes become JSON Pointers
  op: Op;
  value?: unknown;      // replacement payload (strings starting with $ can be JSONPath lookups)
  target?: string;      // destination pointer or JSONPath for move/rename
  allowEmptyMatcher?: boolean; // silence zero-match warnings when intentional
  allowEmptyValue?: boolean;   // allow blank lookups or empty replacements
  valueMode?: "auto" | "literal"; // literal mode keeps $foo text untouched
  targetMode?: "auto" | "pointer" | "jsonpath" | "literal"; // lock how targets are interpreted
  disabled?: boolean;   // skip execution but keep diagnostics visible
}

Execution semantics

  • • Rules execute in the order they appear—earlier mutations change what later matchers see.
  • • Each rule runs its JSONPath matcher against the current working copy before emitting patches.
  • • Matches become JSON Pointers. Every pointer yields one JSON Patch op: remove, replace, move, or rename.
  • • Replace rules resolve their value first: literal mode keeps dollar-prefixed strings, auto mode treats them as JSONPath lookups that must return exactly one value.
  • • Move rules accept JSON Pointers (leading `/`) or JSONPath targets (leading `$`). Use `targetMode` when you need to force one or the other.
  • • Rename rules reuse the matcher pointer but swap the final key. Literal targets become the new key; JSONPath targets resolve against the parent object.
  • • Array removals are applied from highest index to lowest so child positions stay stable for later operations.
  • • Disabled rules stay in the diagnostics timeline without touching the document—handy for experimentation.

The live operation trace in Token Tamer highlights applied vs. skipped steps, so you can tighten matchers or adjust toggles without guesswork.

Error handling

  • • Invalid JSONPath expressions or ambiguous lookups mark the rule with an error and skip its operations.
  • • Value or target lookups that return zero or multiple results are skipped and logged so remaining rules can continue.
  • • Operations that miss their pointer (for example, a move target already removed) are marked as skipped with the reason in the trace.
  • • Enable the allow-empty toggles when zero matches or missing lookup values are expected—warnings disappear but the rule still runs for other hits.
  • • Catastrophic failures leave the original document intact and surface a transformer-level error banner so you can retry safely.

Because the engine works on a cloned document, failed rules never corrupt your source JSON—you can iterate safely and keep the best-performing set.

Tamed payload panel

  • • Pretty vs. compact output lets you read the result or grab the minimized payload you plan to ship to an API.
  • • Copy and download buttons export both the transformed JSON and the JSON Patch stream—no server round-trips required.
  • • Paste an optional JSON Schema to validate the transformed payload locally with Ajv in allErrors mode.
  • • Per-rule switches (allow-empty, disabled) let you keep work-in-progress logic without breaking the pipeline.
  • • The JSON Patch preview mirrors RFC 6902 output so you can replay the same mutations in your own services.
  • • Real-time patcher. Export your rule JSON, load it inside your middleware, then stream API responses through json-remap-engine to apply the same transformations before they hit your apps.

Jump into the live Token Tamer transformer to build rule sets visually, then reuse the same JSON in your automation scripts, CI checks, or npm-based workflows.