T1K

T1K converts one JSON structure into another from a declarative mapping configuration, and converts the result back again. It is a Go package with a command-line tool, depends only on the Go standard library, and ships with the mapping that turns an EnerPlanET calculation payload into a MEME job.

The core idea

A mapping configuration is a list of rules. Each rule pairs a path in the source document with a path in the target document, optionally passing the value through an invertible converter:

{"from": "order.total_cents", "to": "invoice.total", "convert": {"linear": {"divisor": 100}}}

The forward direction (Transform) reads the rule from from to to; the reverse direction (Reverse) reads it from to to from and runs the converter backwards. Every rule is written once and read in both directions, so one configuration yields both transformations and they cannot drift apart.

Paths may contain variables. A variable iterates on the side that is read and is substituted on the side that is written, which is how one rule moves a whole collection and restructures it:

{
  "each": {"from": "order.lines[$i]", "to": "invoice.items{line_$i}"},
  "rules": [
    {"from": "sku", "to": "article"},
    {"from": "qty", "to": "quantity", "convert": "number"}
  ]
}

This rule turns an array of lines into an object keyed line_0, line_1, ... and, in reverse, the object back into the array.

Where to go next

• Installation and the Quickstart
• Using the command line or the Go package
• The mapping language: overview, paths and variables, rules, converters and the reverse direction
• The shipped mapping: EnerPlanET to MEME
• For contributors: architecture and testing

Design goals

• Reversible by construction. A rule is a relation between two documents, not a procedure. Converters are invertible, and what cannot be inverted (a field the target has no place for) is restored from a declared default.
• Strict configurations. Unknown keys, unbalanced variables, unknown converters and malformed conditions are rejected when a configuration is loaded, and every message names the position of the offending rule.
• Faithful documents. A number keeps its digits unless a converter computes it; the input document is never modified; every conversion runs on its own state, so tasks can run in parallel.
• No dependencies. The standard library only, so the package is easy to audit and to embed.

Status

T1K is pre-1.0. Before 1.0, a minor release may change the configuration format or the keys the shipped mapping generates; such changes are listed in the changelog with the keys concerned.