Documentation
DataMapper
Attaching Schemas

Attaching Schemas

Overview

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.

Note

If the data is not structured and just a primitive value, you don’t need to attach a schema file.

Attaching a Schema

Follow these steps to attach a schema file to Source Body, Target Body, or Parameters:

  1. Place your schema file (.xsd or .json) in the workspace directory
  2. Click “Attach a schema” in the Source Body, Target Body, or Parameters section
    Click to attach a schema
    Click to attach a schema
    Click to attach a schema
  3. Click the file button in the modal
    Select schema file
    Select schema file
    Select schema file
  4. Select your schema file
    Choose the schema file
    Choose the schema file
    Choose the schema file
Tip

You can select and upload multiple schema files at once.

Selecting multiple schema files at once
Selecting multiple schema files at once
Selecting multiple schema files at once

  1. For XML schemas only: Choose the root element - Select which top-level element to use if your schema defines multiple
    Choose root element for XML schema
    Choose root element for XML schema
    Choose root element for XML schema
  2. Click Attach
    Confirm schema attachment
    Confirm schema attachment
    Confirm schema attachment
  3. 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.
    Schema rendered as a tree
    Schema rendered as a tree
    Schema rendered as a tree

Detaching 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.

Important

Detaching a schema will remove all mappings associated with that schema. This action cannot be undone.

Understanding JSON Field Labels

Note

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:

LabelMeaning
mapObject field
arrayArray field
stringString field
numberNumber field

Field Label Examples

JSON schema fields are rendered with type-based labels in the tree view. Here’s how different field types appear:

JSON schema field types in the tree view
JSON schema field types in the tree view
JSON schema field types in the tree view

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, map represents an unnamed object
  • Primitive types like string, number, boolean indicate the data type
  • Complex types like map (object) and array represent structured data

Array Fields and Collections

Important

For array fields, the children are the collection items, not the array itself. Collection fields are marked with a layer icon Collection icon. The map type field (child of the array field) is the actual collection field that you’ll use in for-each mappings.

Array field with collection children
Array field with collection children
Array field with collection children

JSON Parameter References

When using structured JSON parameters, they’re internally converted to XML. Reference them with a -x suffix in XPath expressions:

  • Parameter Account becomes $Account-x
  • Parameter Cart becomes $Cart-x
Complete JSON mapping example showing -x suffix usage
Complete JSON mapping example showing -x suffix usage
Complete JSON mapping example showing -x suffix usage
Tip

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.

Next Steps

Now that you have schemas attached:

  1. Create simple mappings between source and target fields
  2. Add conditional logic for complex transformations
  3. Use the XPath editor for advanced expressions
docs