Chapter 5. Kaoto DataMapper
The Kaoto DataMapper is a visual tool for creating data transformations in Apache Camel routes. It provides a graphical interface to map data between XML and JSON structures using drag-and-drop operations, eliminating the need to write complex XSLT code manually.
Whether you’re transforming XML to JSON, merging multiple data sources, or applying complex business logic to your data, the DataMapper helps you:
- Map data visually using drag-and-drop between source and target fields
-
Work with schemas to visualize
XMLandJSONdata structures - Create conditional logic with if, choose-when-otherwise, and for-each mappings
-
Build complex transformations using the
XPathexpression editor - Test and validate your mappings in real-time
The DataMapper generates optimized XSLT 3.0 code that executes at runtime, giving you the power of XSLT without writing it manually.
5.1. Getting Started with Kaoto DataMapper
To use the DataMapper for creating data transformations, you need to add and configure a DataMapper step in your Camel route. This guide covers the essential steps to get started with the DataMapper interface.
5.2. Adding a DataMapper step
Now, add a DataMapper step to your Camel route. The DataMapper provides a visual interface for creating data transformations without writing XSLT code manually.
Add a Kaoto DataMapper step in your Camel route. When you
Append,Prepend, orReplacea step in the Kaoto Design view, you can find the Kaoto DataMapper step in the catalog.
Click the added Kaoto DataMapper step in the Kaoto Design to open the config form.
In the config form, click the
Configurebutton, to open the visual DataMapper editor.
This will open the visual DataMapper editor where you can create your data mappings.
5.3. Understanding the Interface
The DataMapper editor is divided into two main sections that represent the data transformation flow:
5.3.1. Source Section (Left Side)
The Source section represents where your data comes from - the input side of your mappings. This is where the DataMapper step reads the data from.
- Source Body - The incoming Camel Message Body (the main data payload)
- Source Parameters - Additional data from Camel Variables and Message Headers
Think of this as the input side of your transformation - the data you’re reading from.
5.3.2. Target Section (Right Side)
The Target section represents where your data goes to - the output side of your mappings. This is where the DataMapper step writes the transformed data.
- Target Body - The outgoing Camel Message Body (the transformed result)
Think of this as the output side of your transformation - the data structure you’re creating.
You can adjust the font size in the DataMapper interface to match your preference. Use the + and - magnifier icons in the toolbar to make the text larger or smaller for better readability.
5.4. Working with Parameters
Parameters allow you to access Camel Variables and Message Headers in your mappings. This is useful when you need to combine data from multiple sources in your transformation.
5.4.1. Adding a Parameter
Follow the below steps to add a parameter:
Click the plus + button on the right side of the
Source Parameterstitle.
Now type the parameter name and click the check button on the right.
When you have many parameters, you can improve readability by hiding them visually. Click the eye icon next to the Parameters section to toggle the visibility of the parameter list.
While Camel Exchange Properties are also mapped to Parameters in current camel-xslt-saxon implementation, after the Camel Variables has been introduced, it is no longer recommended to store application data into Camel Exchange Properties. We encourage to use Camel Variables instead.
5.4.2. Deleting a parameter
To remove a parameter, click the trash icon next to it and confirm the deletion.
You then have to confirm the deletion by clicking the
Confirmbutton.
The parameter is deleted.
If the parameter is used in any mappings, those mappings will become invalid after deletion. Review your mappings before removing parameters.
5.4.3. Renaming the XSLT File
By default, the DataMapper generates an XSLT file with an auto-generated name. You can rename this file to give it a more meaningful name that reflects the transformation’s purpose.
Steps:
- Click the DataMapper step in the Kaoto Design view to open the config form
Click the pencil icon next to the file name in the Document field to make it editable
- Type the new name for your XSLT file
Click the check button to confirm, or the cancel button to discard
5.5. Attaching Document schema files
Schemas define the structure of your data and enable the visual tree representation in the DataMapper. The DataMapper supports both XML Schema (XSD) and JSON Schema files for Source Body, Target Body, and Parameters.
If the data is not structured and just a primitive value, you don’t need to attach a schema file.
Follow these steps to attach a schema file to Source Body, Target Body, or Parameters:
-
Place schema file (
.xsdor.json) in the workspace directory. Click
Attach a schemabutton in one of theSource Body,Target BodyorParameterssections.
In the Attach schema modal, click the file button.
Select the schema file to attach.
NoteYou can select and upload multiple schema files at once.
For XML schemas only: Choose the root element - Select which top-level element to use if your schema defines multiple.
Click
Attachbutton.
The document structure appears as a tree - The schema is parsed and rendered as an expandable tree view, showing all elements, attributes, and their hierarchical relationships. You can now navigate through the structure and create mappings by dragging fields between source and target sections.
5.6. Detaching a schema
Similar to attaching a schema you can also remove / detach a schema.
To remove a schema from Source Body, Target Body, or Parameters, click the Detach schema button Detach schema button and confirm the action.
Detaching a schema will remove all mappings associated with that schema. This action cannot be undone.
5.7. Understanding JSON field labels
Kaoto DataMapper uses XSLT 3.0 json-to-xml() and xml-to-json() functions to support JSON mappings. The field labels reflect this internal representation.
JSON schemas use type-based labels since fields can be anonymous:
| Label | Description |
|---|---|
|
| Object field |
|
| Array field |
|
| String field |
|
| Number field |
5.7.1. Field Label Examples
JSON schema fields are rendered with type-based labels in the tree view. Here’s how different field types appear:
Understanding the labels:
-
Named fields display as
type [@key = FieldName]- For example,string [@key = AccountId]represents a string field named "AccountId" -
Anonymous fields show only the type - For example,
maprepresents an unnamed object -
Primitive types like
string,number,booleanindicate the data type -
Complex types like
map(object) andarrayrepresent structured data
5.7.2. Array Fields and Collections
For array fields, the children are the collection items, not the array itself. Collection fields are marked with a layer icon <img src="datamapper-collection-field.png" alt="Collection icon" style="display: inline; height: 1.2em; vertical-align: middle;">. The map type field (child of the array field) is the actual collection field that you’ll use in for-each mappings.
5.8. JSON Parameter References
When using structured JSON parameters, they’re internally converted to XML. Reference them with a -x suffix in XPath expressions:
-
Parameter
Accountbecomes$Account-x -
Parameter
Cartbecomes$Cart-x
When creating mappings through drag and drop, Kaoto DataMapper automatically handles the -x suffix. You only need to remember this when editing XPath expressions manually.
5.9. Creating Mappings
Once you have schemas attached, you can create mappings between source and target fields.
The DataMapper offers two primary methods:
- drag-and-drop for quick mappings and
- XPath expressions for more control
5.10. Drag and Drop Mapping
The easiest way to create a mapping is by dragging a source field onto a target field. A line will be drawn between the fields to visualize the connection.
5.10.1. Map the Name Field
Drag-and-drop is the fastest way to create simple field mappings. The DataMapper automatically generates the correct XPath expression for you.
5.11. Container Mappings
When you drag a container field (a field that contains other fields, such as an XML element with child elements or a JSON object with properties) onto another container field, the DataMapper automatically maps their matching children — you don’t need to connect each child field individually.
5.11.1. How Container Mapping Works
- Drag a container field from the source tree onto a matching container field in the target tree
- The DataMapper automatically pairs children by name and creates individual mappings for each match
- This works recursively — nested containers are also matched and mapped automatically
- Children that exist only on one side are skipped
For XML schemas, children are matched by element name and namespace. For JSON schemas, children are matched by property key. When mapping between XML and JSON, children are matched by name.
5.11.2. Collection Mappings
When both the source and target fields are collections (marked with the collection icon), the DataMapper additionally wraps the mapping in a for-each loop that iterates over each item in the source collection.
5.11.3. Mapping Line Styles
After creating a container mapping, you’ll notice different line styles in the mapping view:
Regular — A solid gray line. A simple field-to-field mapping.
Copy-of — A double dark line. The source and target XML containers have identical structure (same name and namespace), so the DataMapper copies the entire subtree efficiently.
Complete — A dashed line with long dashes. All target children are mapped, and all nested containers among them use copy-of.
Partial — A dashed line with short dashes. Some target children are mapped, but not all have a matching source field, or nested containers are mapped field-by-field.
A partial mapping is not an error — it simply means some target fields don’t have a corresponding source field. You can add individual mappings for the remaining fields manually.
5.11.4. When Container Mapping Is Not Available
In some cases, the DataMapper will not allow a container-to-container mapping:
- Mismatched field types: A container field can only be mapped to another container field. Dragging a container onto a leaf field (or vice versa) will be rejected.
- No compatible children: If the source and target containers have no children with matching names, the mapping cannot be created.
- JSON arrays: JSON array wrapper fields cannot be mapped directly — expand the array and map its children instead.
If a drop is rejected, try mapping the children individually instead of the parent container.
5.12. XPath Expression Mapping
For more control over your mappings, you can type XPath expressions directly.
5.12.1. Creating a Mapping with XPath
Click the 3 dots context menu on the target field and select
Add selector expression.
Then enter the XPath expression to define the mapping.
XPath expressions give you full control over data transformation, including string manipulation, calculations, and conditional logic. For complex expressions, consider using the XPath Editor.
5.13. Comment on a Mapping
Once a mapping is created, you can also comment on it.
Click the 3-dot menu on the target field
Add your comment
5.14. Delete a Mapping
To delete a mapping, click the trash bin icon next to the target field and confirm the deletion.
Deleting a mapping is permanent and cannot be undone. Make sure you want to remove the mapping before confirming.
5.15. Conditional Mappings
The DataMapper supports three types of conditional mappings to handle complex transformation logic:
-
if- Execute mapping only when a condition is met -
choose-when-otherwise- Branch based on multiple conditions -
for-each- Iterate over collection fields (arrays)
5.15.1. Creating an if mapping
Create a mapping that only executes when a specific condition is true.
Click the 3 dots context menu on the target section’s field. Then select
wrap with "if"to create a mapping.
Configure the
ifcondition. You can drag the source field and drop it into the input field to build a condition, or alternatively type everything manually.
Create the mapping for when the condition is true.
You can drag source fields into the condition input to quickly build expressions like $sourceField > 100 or $status = 'active'.
5.15.2. Creating a choose-when-otherwise mapping
Create branching logic with multiple conditions, similar to switch-case statements.
Click the 3 dots context menu on the target section’s field. Then select
wrap with "choose-when-otherwise"to create a mapping.
Configure when and otherwise conditions - Similar to if mapping, configure the condition and create mappings for both when and otherwise branches
Add more when branches (optional) - If you need multiple conditions, click the 3-dot menu on the choose field and select “Add when” to create additional when branches. Each branch can have its own condition and mappings.
The otherwise branch executes when none of the when conditions are satisfied, providing a default fallback.
5.15.3. Creating a for-each mapping
When working with arrays or repeating elements, use for-each mappings to transform each item in the collection. Collection fields are identified by a layer icon Layer icon in the document tree.
Identify the target collection field - Look for fields marked with the layer icon Layer icon, indicating they contain multiple items.
Create the for-each mapping - Click the 3 dots context menu on the target section’s collection field. Then select
Wrap with "for-each"to create a mapping.
Specify the source collection - Choose which source collection to iterate over. This determines what data will be processed for each target item.
Map the collection item fields - Create mappings for individual fields within each collection item. These mappings will be applied to every item in the collection.
Inside a for-each mapping, field paths are relative to the collection item. For example, if iterating over Items, you reference Name instead of Items/Name.
5.15.4. Creating multiple for-each mappings
Merge multiple source collections into a single target collection by adding multiple for-each mappings.
After creating a first
for-eachmapping by following previous section, clickAdd Conditional Mappingin the placeholder below the addedfor-eachmapping
Click
Wrap with "for-each"
Configure the second collection mappings - Select the second source collection to iterate over, then create field mappings for each item. This allows you to merge data from multiple collections into a single target array, combining items from different sources.
Here is a demo screencast for merging 2 source collection fields with multiple for-each mappings.
This technique is useful for merging data from multiple sources, such as combining orders from different systems into a single output array.
5.16. XPath Editor
The XPath Editor provides a powerful way to create complex data transformations beyond simple field-to-field mappings. While drag-and-drop is great for basic mappings, the XPath Editor lets you combine fields, apply functions, perform calculations, and implement sophisticated business logic.
When to use the XPath Editor:
- Combining multiple source fields into one target field
- Applying string manipulation (concatenation, substring, case conversion)
- Performing mathematical calculations
- Using conditional expressions within a single mapping
- Applying XPath functions for date formatting, number formatting, and more
The XPath Editor is under active development. Current features include drag-and-drop for fields and functions, with more syntax assistance planned for future releases.
5.16.1. Opening the XPath Editor
To edit or create complex XPath expressions, click the pencil icon next to a target field that has an existing mapping. This will launch the editor where you can modify and build the expression for that mapping.
5.16.2. Building XPath Expressions
The XPath Editor interface provides two main areas: a palette on the left with fields and functions, and an expression editor on the right.
5.16.2.1. Adding Fields
You can add source fields to your expression by:
- Typing directly - Enter field paths manually using XPath syntax
Drag and drop - Drag fields from the Fields tab and drop them into the editor
5.16.3. Using XPath Functions
The XPath Editor provides access to a comprehensive library of functions for data transformation:
String Functions:
-
concat()- Combine multiple strings -
substring()- Extract part of a string -
upper-case(),lower-case()- Change text case -
normalize-space()- Remove extra whitespace
Numeric Functions:
-
sum(),avg(),min(),max()- Aggregate calculations -
round(),floor(),ceiling()- Number rounding -
format-number()- Number formatting
Date/Time Functions:
-
current-date(),current-time()- Get current date/time -
format-date(),format-time()- Format date/time values
Conditional Functions:
-
if()- Inline conditional logic -
choose()- Multi-branch conditionals
To use functions:
Switch to the Functions tab in the left palette.
Drag the function you need and drop it into the editor.
- Fill in the function parameters with field references or literal values
5.16.4. Saving Your Expression
Once you’ve built your XPath expression, click the Close button to apply it to the mapping.
The mapping will now appear in the tree view with your custom XPath expression.
Start with simple expressions and test them before adding complexity. You can always reopen the XPath Editor to refine your expression.
5.17. Advanced Features
Once you’re comfortable with basic mappings and conditional logic, the DataMapper offers advanced features for handling complex transformation scenarios. This guide covers advanced capabilities for working with complex schemas:
- Field Override - Change field types or substitute elements for complex schemas
-
Choice Support - Handle schema choice elements (
xs:choice)
5.17.1. Field Override
Field override allows you to change how a schema field is interpreted in your transformation. The DataMapper supports two types of overrides, both accessed through the same modal dialog:
- Override Type - Change a field’s type to a compatible derived type
- Substitute Element - Replace an element with one from its substitution group
Field override options depend on your schema definitions. To enable type overrides, your schema must define type extensions using xs:extension or xs:restriction.
For field substitutions, your schema must define substitution groups. You can attach additional schema files that extend your base schema to unlock these capabilities.
5.17.1.1. When to Use Field Override
Override Type:
-
The source data uses a derived type (e.g.,
SpecialAddressextendsAddress) - You need to access additional fields defined in a subtype
- The actual runtime data differs from the base schema definition
Substitute Element:
- Working with XML Schema substitution groups
- Need to select a specific concrete element from a group of alternatives
- Handling polymorphic data structures
5.17.1.2. Understanding the Override Modal
When you select "Field Override" from a field’s context menu, the DataMapper opens a modal dialog with radio buttons to switch between two override types:
- Override Type - Lists compatible derived types within the type hierarchy
- Substitute Element - Shows available substitution group members
Use the radio buttons to switch between override types. The modal displays only valid options based on the schema definition, ensuring type safety.
5.17.1.3. Extending Schemas for Field Override
If the Field Override modal shows no available options, your schema may not define the necessary extensions or substitution groups. You can attach additional schema files that extend your base schema:
For Override Type: - Create or attach a schema that extends base types using xs:extension or xs:restriction - Example: A schema defining SpecialAddress that extends Address
For Substitute Element: - Create or attach a schema that defines substitution groups - Example: A schema defining Car, Truck, and Motorcycle as substitutes for Vehicle
Once you attach the extending schema file using the [schema attachment](../02-attaching-schemas/) process, the Field Override modal will display the newly available options.
You can attach multiple schema files to the same DataMapper step. This allows you to work with a base schema and one or more extension schemas that define derived types or substitution groups.
5.17.1.4. Applying an Override Type
Override Type changes a field’s type to a compatible type within the same type hierarchy. Fields with an active override type are marked with a special icon indicator in the document tree.
Steps:
- Right-click on the field you want to override (or use the 3-dot menu)
- Select "Override Field…" from the menu
- Select the "Override Type" radio button in the modal (if not already selected)
- Choose a type from the list of compatible derived types
- The field tree updates to show the new type’s structure
- An icon appears next to the field indicating the override type is active
Override Type preserves compatibility with the original schema by only allowing safe type substitutions within the type hierarchy.
5.17.1.5. Applying a Substitute Element
Substitute Element replaces a schema element with one of its designated substitution elements. Fields with an active substitution are marked with a special icon indicator in the document tree.
Steps:
- Right-click on a field that has available substitutions
- Select "Override Field…" from the menu
- Select the "Substitute Element" radio button in the modal
- Choose a substitute element from the list of substitution group members
- The field updates to reflect the substituted element’s name and structure
- An icon appears next to the field indicating the substitution is active
Override Type and Substitute Element are mutually exclusive on the same field. The modal will show only the applicable options based on the field’s schema definition.
5.17.1.6. Working with Abstract Elements
Abstract elements are special schema elements that cannot be used directly in XML instances - they must be substituted with a concrete implementation. The DataMapper provides two approaches for working with abstract elements.
5.17.1.6.1. Viewing Available Implementations
The DataMapper automatically displays abstract elements with their substitution candidates as children in the document tree. You can create mappings directly to these substitution candidates without explicitly applying a substitution.
You must either create a mapping on a substitution candidate under the abstract field, or apply field substitution.
Method 1: Using Substitute Element Modal
Explicitly select a concrete implementation using the Field Override modal:
Steps:
- Right-click on the abstract element
- Select "Override Field…" from the context menu
- Select the "Substitute Element" radio button in the modal
- Choose a concrete implementation from the list of substitution candidates
- The field updates to show the selected concrete element
Method 2: Using Context Menu
For quick selection, you can use the context menu directly:
Steps:
- Right-click on the abstract element
- Select the concrete implementation directly from the context menu
- The field updates to show the selected element
Use the Field Override modal for detailed selection or the context menu for quick selection. Once selected, the abstract element is replaced with the concrete implementation in the generated XSLT.
5.17.1.7. Identifying Overridden Fields
Fields with active overrides are easy to identify in the document tree:
- Override Type - Marked with an override type icon indicator
- Substitute Element - Marked with a substitution icon indicator
These visual indicators help you quickly see which fields have been modified from their original schema definitions.
5.17.1.8. Resetting a Field Override
To restore the original schema-defined field:
- Right-click on the overridden field (marked with an icon indicator)
- Select "Reset Override" from the context menu
- The field returns to its original type or element
- The icon indicator is removed
Resetting a field override may invalidate mappings that reference fields only available in the overridden version.
5.17.2. Choice Support
5.17.2.1. Understanding xs:choice in Schemas
XML Schema xs:choice defines a set of element options where the behavior depends on the maxOccurs attribute:
- maxOccurs=1 (default): Only one option can appear in a valid XML document
- maxOccurs>1: Multiple instances can appear, potentially mixing different choice options
The DataMapper represents choices as expandable choice groups in the document tree. The mapping interface allows selecting one option at a time, regardless of the maxOccurs value.
5.17.2.2. Selecting a Choice Member
When the document tree contains a choice group, it appears as a collapsible node with the available options listed as children, similar to how abstract elements display their substitution candidates.
Steps:
- Expand the choice group in the document tree
- Right-click on the choice group to open the context menu
- Select the choice member you want to use from the menu
- The selected member expands, showing its child fields available for mapping
- Non-selected members are hidden from the tree
You can change the selected choice member at any time. However, mappings to the previously selected member’s fields will remain in the XSLT and may need to be manually reviewed or removed.
5.17.2.3. Working with Nested Choices
The DataMapper supports nested choice elements. When multiple nested choices are selected, an indicator (e.g., ×2) appears next to the field showing how many choice wrapper levels have been collapsed.
5.17.2.4. Showing All Choice Options
To view all available choice options without a specific selection:
- Right-click on the choice group
- Select "Show All Choice Options"
- All choice members return to their default unselected state
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}