# Mapping lists and nested JSON structures

*Omnistudio Developer Study Guide · Data Mappers · Last updated October 27, 2026 · https://www.certifyforce.com/study-guide/omnistudio-developer/data-mappers/mapping-lists-and-nested-json-structures*

How Data Mapper mappings build the output structure you need: colon paths that rename and reparent nodes, list position indexes, moving a list to another level, turning a list of objects into a list of values, array merging rules, Quick Match and what Preview shows.

- Certification: Salesforce Omnistudio Developer
- Exam section: Data Mappers
- Study guide: https://www.certifyforce.com/study-guide/omnistudio-developer

**Official exam objective:**

> Map source and target data structures to achieve expected output structure.

## What the exam expects

- Rename and reparent fields by mapping an input JSON path to a colon-delimited output path.
- Use list position indexes (`|1`, `|2`) to build or reshape short lists, and know which list shapes can't be converted.
- Move a list to a different level of the hierarchy, and convert a list of objects of any length into a list of values with a formula.
- Predict how a Transform treats arrays mapped to a single object and several lists mapped to one output list.
- Map with Quick Match (Auto Match, Pair) and read the Preview tab correctly.

Key terms: **JSON path** (a colon-delimited route to a node, such as `Site:Contact:Phone`), **list position index** (`|n` after a node, selecting the nth list item), **list of values** (an array of bare values with no keys), **Quick Match** (the dialog that pairs input and output fields), **Auto Match** (pairs fields whose names match).

## Key facts

| Fact | Detail | Source |
|---|---|---|
| Restructure or rename | Map the input path to the desired output path | [Transform mappings](https://help.salesforce.com/s/articleView?id=xcloud.os_dataraptor_transform_data_mappings_46630.htm&language=en_US&type=5) |
| Path delimiter | A colon separates levels | [Use Formulas](https://help.salesforce.com/s/articleView?id=sf.os_use_formulas_in_dataraptors_47540.htm&language=en_US&type=5) |
| List position index | `\|1`, `\|2` after a node selects an item | [Lists](https://help.salesforce.com/s/articleView?id=xcloud.os_list_input_for_dataraptors_47431.htm&language=en_US&type=5) |
| Bare-value list | Can't be converted to a keyed list | [Lists](https://help.salesforce.com/s/articleView?id=xcloud.os_list_input_for_dataraptors_47431.htm&language=en_US&type=5) |
| Change a list's level | Short list with a known number of items only | [List level](https://help.salesforce.com/s/articleView?id=xcloud.os_change_the_hierarchical_level_of_a_list_46934.htm&language=en_US&type=5) |
| Objects to values, any length | Formula `ObjectList:Property`, map its result path | [List of values](https://help.salesforce.com/s/articleView?id=xcloud.os_convert_a_list_of_objects_to_a_list_of_values_46859.htm&language=en_US&type=5) |
| List cast to a primitive | Only the first element is output | [Output Data Types](https://help.salesforce.com/s/articleView?id=xcloud.os_dataraptor_output_data_types_47661.htm&language=en_US&type=5) |
| Several lists to one output list | Order not guaranteed; combine with a formula | [Transform mappings](https://help.salesforce.com/s/articleView?id=xcloud.os_dataraptor_transform_data_mappings_46630.htm&language=en_US&type=5) |
| Auto Match | Matches fields with matching names only | [Configure an Extract](https://help.salesforce.com/s/articleView?id=xcloud.os_define_the_initial_extraction_45906.htm&language=en_US&type=5) |
| Preview decimals | Trailing zeros removed in the Response panel | [Preview and Test](https://help.salesforce.com/s/articleView?id=xcloud.os_preview_test_datamappers.htm&language=en_US&type=5) |

## Check yourself

- Why can't a list like `["Red", "Blue"]` be turned back into keyed nodes?
- When is moving a list to another level with indexed mappings appropriate?
- Why might two input lists mapped to one output list come back in a different order each run?
- What does a Transform return when a two-record array is mapped to a single-object output?

## Sources

- [Map Inputs and Outputs for Transformations](https://help.salesforce.com/s/articleView?id=xcloud.os_dataraptor_transform_data_mappings_46630.htm&language=en_US&type=5)
- [Transforming Lists with Data Mappers](https://help.salesforce.com/s/articleView?id=xcloud.os_list_input_for_dataraptors_47431.htm&language=en_US&type=5)
- [Change the Hierarchical Level of a List](https://help.salesforce.com/s/articleView?id=xcloud.os_change_the_hierarchical_level_of_a_list_46934.htm&language=en_US&type=5)
- [Convert a List of Objects to a List of Values](https://help.salesforce.com/s/articleView?id=xcloud.os_convert_a_list_of_objects_to_a_list_of_values_46859.htm&language=en_US&type=5)
- [Preview and Test Data Mappers](https://help.salesforce.com/s/articleView?id=xcloud.os_preview_test_datamappers.htm&language=en_US&type=5)
- [Configure an Omnistudio Data Mapper Extract](https://help.salesforce.com/s/articleView?id=xcloud.os_define_the_initial_extraction_45906.htm&language=en_US&type=5)
- [Use Formulas in Omnistudio Data Mappers](https://help.salesforce.com/s/articleView?id=sf.os_use_formulas_in_dataraptors_47540.htm&language=en_US&type=5)
- [Omnistudio Data Mapper Output Data Types](https://help.salesforce.com/s/articleView?id=xcloud.os_dataraptor_output_data_types_47661.htm&language=en_US&type=5)
- [Supported Data Mapper and Integration Procedure Data Types](https://help.salesforce.com/s/articleView?id=xcloud.os_omnistudio_data_mapper_and_integration_procedure_data_types.htm&language=en_US&type=5)

## About the full unit

The "Core concepts", "Exam traps" and "Worked scenario" sections of this unit, its 5 linked practice questions, and unlimited timed mock exams are included with the Omnistudio Developer pack (USD $19): https://www.certifyforce.com/practice-exams