# Flux-Map: A Pure-JSON Mapping DSL for LLM-Friendly Data Transformation **Version:** 0.9 (Draft) **Status:** Proposal / Reference **Authors:** — **Last Updated:** 2025-09-19 --- ## Abstract Flux-Map is a **pure-JSON, configuration-only** mapping language for transforming JSON documents. It is designed to be **LLM-friendly** (easy to author/repair by language models), **safe** (no inline code, no eval), and **explicit** (no implicit scopes or magic). The core consists of a **small base op set** (navigation, structure, arrays, math/strings, scoping) and an optional **sugar layer** that compiles down to the base. The DSL is **output-shape-first**: you author the target JSON shape and populate leaf nodes with Flux-Map operation nodes. --- ## Goals & Non-Goals ### Goals - Pure JSON config – no embedded code or templating. - Explicit scoping – all iterators bind named variables via `$var`. - Minimal base ops with deterministic semantics. - Optional sugar operators that **desugar** to base ops. - Self-documenting and schema-validatable (JSON Schema provided). - Easy array handling (map/filter/reduce), composable, predictable. - Friendly to tooling: tracing, visualization, static linting. ### Non-Goals - No domain-specific helpers; only generic operations. - No reading from partially built output (avoid cycles/ordering issues). - Not a general programming language; it's a mapping DSL. --- ## Design Principles 1. **Configuration, not code.** Every operation is a JSON node; engines never eval strings. 2. **Explicit is better than implicit.** Iterators must name variables; no ambient `@`. 3. **Small core, sugar on top.** Implement a tiny base once; add sugar as conveniences. 4. **Acyclic by construction.** Output is computed from source + config; not from itself. 5. **Deterministic & traceable.** Same input + config ⇒ same output; every field traceable. --- ## Quick Start You define the **target shape** and fill leaf values with Flux-Map nodes. ```json { "$meta": { "name": "CustomerProjection", "version": "1.0" }, "customer": { "id": { "$ref": "$.user.id" }, "name": { "$ref": "$.user.fullName" }, "email": { "$ref": "$.user.email" }, "birthDate": { "$ref": "$.user.dob" }, "country": { "$ref": "$.user.address.countryCode" }, "lifetimeValue": { "$round": { "value": { "$divide": { "a": { "$sum": { "over": { "$pluck": { "over": { "$ref": "$.orders" }, "path": "totalCents" } } } }, "b": 100 } }, "digits": 2 } }, "orders": { "$map": { "over": { "$ref": "$.orders" }, "as": "o", "body": { "orderId": { "$get": { "from": { "$var": "o" }, "path": ["id"] } }, "createdDate": { "$slice": { "value": { "$get": { "from": { "$var": "o" }, "path": ["createdAt"] } }, "start": 0, "end": 10 } }, "total": { "$round": { "value": { "$divide": { "a": { "$get": { "from": { "$var": "o" }, "path": ["totalCents"] } }, "b": 100 } }, "digits": 2 } }, "lines": { "$map": { "over": { "$get": { "from": { "$var": "o" }, "path": ["items"] } }, "as": "it", "body": { "sku": { "$get": { "from": { "$var": "it" }, "path": ["sku"] } }, "qty": { "$get": { "from": { "$var": "it" }, "path": ["qty"] } }, "unit": { "$round": { "value": { "$divide": { "a": { "$get": { "from": { "$var": "it" }, "path": ["priceCents"] } }, "b": 100 } }, "digits": 2 } }, "title": { "$get": { "from": { "$ref": "$.catalog.bySku" }, "path": [ { "$get": { "from": { "$var": "it" }, "path": ["sku"] } }, "title" ] } }, "category": { "$get": { "from": { "$ref": "$.catalog.bySku" }, "path": [ { "$get": { "from": { "$var": "it" }, "path": ["sku"] } }, "category" ] } } } } } } } } } } ``` --- ## Source Model Used in Examples ```json { "user": { "id": "u_123", "fullName": "Ada Lovelace", "email": "ada@example.com", "address": { "street": "1 Computing Way", "city": "London", "countryCode": "GB" }, "dob": "1815-12-10" }, "orders": [ { "id": "o1", "totalCents": 2599, "createdAt": "2024-06-01T10:00:00Z", "items": [ { "sku": "BK-001", "qty": 1, "priceCents": 1999 }, { "sku": "USB-042", "qty": 2, "priceCents": 300 } ] }, { "id": "o2", "totalCents": 1200, "createdAt": "2024-08-20T12:00:00Z", "items": [ { "sku": "BK-002", "qty": 1, "priceCents": 1200 } ] } ], "catalog": { "bySku": { "BK-001": { "title": "Analytical Engine Primer", "category": "Books" }, "BK-002": { "title": "Difference Engine Guide", "category": "Books" }, "USB-042": { "title": "USB Cable", "category": "Accessories" } } } } ``` --- ## Semantics Overview - **Evaluation model:** Bottom-up evaluation of nodes; plain JSON values are left as-is; op nodes are reduced to values. - **Purity:** Nodes are pure functions of their inputs. No side effects. - **Scope:** `$with` and iterators (`$map/$filter/$reduce`) introduce named variables accessed via `{"$var":"name"}`. Shadowing is disallowed. - **Missing values:** Accessing a missing path yields `null` (configurable to error in strict mode). `$coalesce` provides defaults. - **Acyclic:** Output values never read previously computed output fields; reuse via `$with` locals instead. --- ## Operator Reference > Each entry shows a **bold op name** with its **category**, a compact **signature**, a one-line explanation, and a small **example**. ### Navigation & Literals #### $ref — navigation **Signature:** `{"$ref":"$.path.to.value"}` → Read static root path. ```json { "$ref": "$.user.email" } ``` #### $const — literal **Signature:** `{"$const": }` → Embed a literal value. ```json { "$const": { "ok": true } } ``` #### $get — navigation **Signature:** `{"$get": { "from": , "path": [ , ... ] }}` → Dynamic object/array access with computed segments. ```json { "$get": { "from": { "$ref": "$.catalog.bySku" }, "path": ["BK-001", "title"] } } ``` ### Structure #### $merge — structure **Signature:** `{"$merge": [

See Also

Related Projects