JSON Mapper

Convert JSON from one schema to another

Every integration has the same chore at its centre: one system produces JSON in its shape, and another expects JSON in a different one. Field names differ (order_id versus id), objects are grouped differently (shipping.street versus address.line1), values have the wrong types ("129.00" instead of 129), and lists of items need reshaping one by one. This JSON mapper does that conversion visually: show it the JSON you have and the shape you need, and it builds the mapping between them.

The result updates as you work, and the same mapping is available as a JavaScript function, so the tool is both a one-off converter and a way to write transformation code without writing it by hand.

How a mapping is built

The target shape is listed field by field in the Field mapping table. Each target field gets its value from one of three places:

• A source field — pick any path from the source JSON, such as customer.email_address or line_items[].qty.
• A template — combine several source fields with text, such as {{customer.first_name}} {{customer.last_name}}.
• A fixed value — the same value on every record, written as text or as JSON (42, true, null, ["a"]).

Automatic field matching

You rarely start from a blank table. Field names are split into words whatever the naming convention — camelCase, snake_case, kebab-case, or spaces — and common synonyms are treated as the same word: qty and quantity, zip, postcode and postal code, title and name, telephone, mobile and phone, street and address line 1. Each target field is then scored against every source field, with extra weight when the parent objects match and when both sit at the same depth of array nesting.

The strongest pairs are assigned first and each source field is used once, so a weak match can't steal a field that belongs to a better one. Auto-matched fields are labelled auto; change any of them from the dropdown, where the closest candidates are suggested at the top. The wand button re-runs matching from scratch after you change the inputs.

Mapping arrays and nested lists

Paths use [] to mean every item of an array, which is how lists are reshaped. When the fields inside a target array, such as items[].sku and items[].price, are mapped to fields inside a source array, such as line_items[].product_sku and line_items[].unit_price, the target array gets one item per source item. Nested lists follow the same rule level by level — orders containing line items map to orders containing items.

A target field outside any array can still read from inside one; it then takes the first item, and the table says so beside the field so the behaviour is never a surprise. And when the whole source is a list of records but the target describes a single record, Map each record runs every record through the same mapping.

Converting value types

APIs disagree about types as often as about names. Each mapped field has a conversion setting:

• Auto — converts to the target field's type when the conversion is lossless: "129.00" to 129, "true" or "yes" to true, 42 to "42". Anything else passes through unchanged.
• As is — copies the value exactly, whatever the target type.
• Text, Number, Boolean — force a type: Text writes objects and arrays as JSON strings; Boolean understands true/false, yes/no, y/n, on/off, and 1/0.
• UPPERCASE, lowercase, Trim spaces — tidy string values, such as country codes or emails.

Using a JSON Schema as the target

If the receiving API publishes a JSON Schema, paste it as the target instead of an example. Properties become target fields in order, local $ref definitions under $defs or definitions are followed, allOf is merged, and the first non-null branch of anyOf or oneOf is used. Required properties are flagged until they are mapped.

The result is then validated against the schema as you map, and the status bar under the result shows either a match or the first problem, with every issue listed on hover. To test other documents against the same schema, use the JSON Schema validator.

Generate JavaScript mapping code

The JavaScript tab turns the mapping into a standalone function, mapJson(src), with no dependencies. It reads the same paths, applies the same conversions, and handles arrays and missing values exactly as the preview does, so you can paste it into a Node.js service, a browser app, or a serverless function and trust it to behave the way you tested it here. Pair it with JSON to TypeScript to generate interfaces for the input and output shapes.

JSON mapper, JSONata, JOLT, or jq?

Expression languages such as JSONata, JOLT, and jq are powerful, but you have to learn their syntax before you can reshape anything, and a transformation written in them is hard to review at a glance. A visual mapper suits the common case — renaming, regrouping, converting, and reshaping lists — and produces ordinary JavaScript at the end. For pulling specific values out of a document rather than reshaping it, the JSONPath tester is the quicker tool, and to check how two versions of a payload differ after a mapping change, use the JSON diff checker.