Home /  Mappings / 

Getting started with Mappings

Mappings is a robust JSON-to-JSON data transformation engine that enables developers to define field mappings in an intuitive UI – and then invoke those mappings programmatically via an API.

Mappings is composed of two parts:

  • a browser-based tool that allows users to create and test JSON-to-JSON data transformations
  • an API that can be used to programmatically invoke defined mappings at web scale.

Let's get started.


To get ourselves familiar with Mappings, we're going to build a simple mapping transforming data from one API shape:

  "product": {
    "id": "QL-5490S",
    "price": "USD 500"

to another:

  "product_number": "QL-5490S",
  "price": {
    "currency": "USD",
    "amount": 500

By the end of this tutorial you'll know how to:

  • create a new mapping from scratch
  • write JSONata expressions to transform data
  • detect and fix transformation errors
  • execute a mapping via an API

Build & launch your first mapping

To get started, log in to Stedi's dashboard. You'll see an overview of all available Stedi products, with links to other guides, API references, and more.

Screenshot of Stedi's dashboard homepage

To begin, click on Start mapping.

Screenshot of Mappings section with a Start mapping button

You will be redirected to Mappings product page.

Screenshot of an empty Get started with Mappings page with a button to create a mapping

Since we're just getting started, there are no mappings yet - let's create one.

Screenshot of Create Mapping popover

You'll be redirected to mapping wizard flow (don't worry, there are only 3 steps before we can start building a mapping). First, you need to select a source schema.

Screenshot of an empty mapping source schema editor

Source schema is derived from an example JSON file we're going to provide here (same with target schema which we're going to create in a second).

On this page, we can either provide our own JSON file or use a predefined sample. If you'd like to follow along with this guide, paste in the following snippet into the editor…

  "product": {
    "id": "QL-5490S",
    "price": "USD 500"
Screenshot of a mapping source schema editor with sample data

… and click Next. You'll be redirected to a Target schema page - to follow along, paste the following snippet into the editor:

  "product_number": "QL-5490S",
  "price": {
    "currency": "USD",
    "amount": 500
Screenshot of a mapping target schema editor with sample data

After clicking Next, you'll be redirected to Add target keys to map page, where you can choose which keys from target schema you want to map to.

Note: you don't have to select all keys from target schema to map to. Use the tree view to select only the keys you need for your use case. You can always add/remove keys from mapping later.

Click on Select all and you're ready to start building a mapping 🚀

Screenshot of add target keys to map tree view

Click on Start mapping to proceed.

You will be redirected to Mapping Editor, which should look similar to this:

Screenshot of an empty mapping editor

Mapping editor is divided into four resizable panes:

  • Source JSON view - displays the structure we are starting with
  • Target JSON view - displays the structure we want to map to
  • Mapping canvas - a place where you'll transform your source data to the target shape
  • Output JSON view - displays the output of currently edited mapping


For this sample mapping we'd like to achieve the following:

  • Target JSON contains a product_number field. This field should be populated with a string id inside the product object in a Source JSON.
  • Target JSON contains a price object with currency and amount fields. This field should be populated with data contained in price string inside of product object in Source JSON.
  • Example: if price contains "USD 500", currency should be set to "USD" and amount should be set to 500.

Writing mapping expressions

Let's start with product_number. As we've established earlier, this field should be mapped to value of id field in Source JSON.

Screenshot of a sample source JSON

The mapping editor makes retrieving paths to such values straightforward, click on id key to copy a path to it.

Screenshot of a sample source JSON

Once the path has been copied to the clipboard, paste it in a text input next to product_number. The Mapping Canvas should look like the following:

Screenshot of a mapping editor with product.id already mapped

Take a look at Output JSON - the id value from Source JSON is now showing in the product_number field. Congrats, you have just mapped your first field using Mappings!

Transforming values for price object in Target JSON will be a little more involved, luckily we can use a Transformation editor to help us. To continue click on the Open transformation editor button next to currency text input.

Screenshot of a Open transformation editor button

A Transformation editor will open:

Screenshot of an empty transformation editor

There's lots of useful information here - header tells us that we're trying to map to currency output field within price object, we can view both Source JSON and Target JSON, and most importantly - write a mapping expression in Transformation section.

Start by typing product - the editor will guide you, providing autocomplete suggestions…

Screenshot showing autocomplete functionality in transformation editor

...which can be accepted by hitting ENTER on your keyboard.

Screenshot of a transformation editor with product.price already mapped

Taking a look at the product.price string ("USD 500"in our example), we can see that it contains both currency and amount information, separated by a space.

Mappings come with many built-in functions that will help you build any data transformation. All functions begin with a $ character. Type $ to see an autocomplete box with the list of all supported functions.

Mappings is powered by an open-source query and transformation language called JSONata, which comes with a large number of built-in functions and expressions.

Screenshot of a transformation editor with all JSONata functions listed

Select $split function and write a $split(product.price, " ") expression to spit product.price by a space, producing an array of strings visible in Output preview view.

Screenshot of a transformation editor with the body of a $split expression

The goal is to map a currency field - to do that, select the first item of an array by appending [0] to our expression.

Final result: $split(product.price, " ")[0]

Screenshot of a transformation editor with product.price[0] already mapped

Click on Confirm to proceed. Mapping editor will now be updated and you'll be able to verify that currency field was mapped properly.

Screenshot of a mapping editor with currency target document field already mapped

Output JSON now contains both product_number and currency fields, only amount remains.

To map the value for amount field, open its Transformation editor and paste the following expression $split(product.price, " ")[1].

Screenshot of a transformation editor with product.price[1] already mapped

Instead of selecting the first element of an array, we're selecting a second one to retrieve the value of "500". Click on Confirm to proceed.

Screenshot of a wrong type warning in mapping editor

Looks like we have a warning, let's investigate by hovering over it.

Screenshot of Expected a number but the result is a string warning

Got it! An amount field in Target JSON is a number (notice the lack of "" around 500) and our mapping expression produced a string. Luckily this is an easy fix, solved by Click to wrap the whole expression in a $number function button.

Screenshot of mapping editor with an expression wrapped in a $number function

You have finished building your first mapping, congrats! Make sure to Save your progress to avoid losing the results of your hard work.

Screenshot of mapping editor after the mapping was saved

Invoking a mapping via an API

Now that we have created a mapping, we'd like to use it to transform data via an API. To get started, click on the Launch button.

You'll see a popover containing multiple code snippets helping you invoke your freshly created mapping using an API.

Screenshot of a Node.js + Axios snippetScreenshot of a cURL snippet

Like all Stedi APIs, Mappings API requires an API key to use it. If you don't have one, you'll see a No API keys notification.

Screenshot of No API Keys warning

If you don't have a Stedi API key, you can create one by clicking on Create a key now in Launch popover. Check out our Authentication guide to learn more.

Screenshot of API Keys page on Stedi's dashboard

Going back to Launch mapping view, click on Copy snippet to store the autogenerated code in your clipboard.

Screenshot of a cURL snippet

You're now ready to start executing your mapping via an API. All Stedi products are API driven, allowing you to integrate them in your production systems right away.

As a simplified example, let's import the curl snippet above into Insomnia (you can use Postman or any other API client as well).

For instance, you can pass the Source document as a request body and verify that the results from API match what you saw in Output JSON section in the mapping editor.

Screenshot of Insomnia tool sending a default request to Mappings API

Mappings can be invoked with any JSON input, to double-check our mapping is properly transforming arbitrary data, you can invoke it with:

  "product": {
    "id": "MY_TEST_PRODUCT_ID",
    "price": "EUR 3000"
Screenshot of Insomnia tool sending a custom request to Mappings API

Congrats! 🎉

Your brand-new mapping is now ready for production usage.

Next steps

Visit the Mappings Documentation to learn more about our product. To learn more about expressions supported by Mappings, consult the JSONata Functions list.

You don't have to reinvent the wheel, we've compiled a list of common transformations in our JSONata Cheatsheet.

The Mappings API is billed based on usage. There are no minimum fees, monthly commitments, or upfront costs to use this product. Check out Pricing page for more details.

If you have any feedback on how we can improve this post or would like to get in touch with the team, send us a note at team@stedi.com.

IntroductionBuild & launch your first mappingRequirementsWriting mapping expressionsInvoking a mapping via an APINext steps