Field Context Menu

Overview

Right-click any field node in the source or target tree to open the field context menu. This menu provides schema-level operations that change how a field is interpreted in your transformation — distinct from the ⋮ mapping context menu, which controls what XSLT instructions are generated.

The field context menu offers:

• Field Override — Change a field’s type or substitute it with another element from its substitution group
• Choice Support — Select, change, or clear a member of an xs:choice field

Field Override

Field Override allows you to change how a schema field is interpreted in your transformation. The DataMapper supports two override modes, both accessed through the same Field Override modal:

• Override Type — Change a field’s type to a compatible derived type (emits xsi:type in the generated XSLT)
• Substitute Element — Replace an element with one from its substitution group

When to use Field Override

Override Type:

• The source data uses a derived type (e.g., SpecialAddress extends Address)
• 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

The Field Override modal

Open it by right-clicking a field and selecting “Override Field…” from the context menu.

The modal has two sections:

• Override Mode — radio buttons to choose Override Type or Substitute Element
• Selector — a typeahead input listing compatible types or substitution candidates; start typing to filter the list

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. Attach additional schema files using the schema attachment process to unlock these capabilities.

Applying an Override Type

Override Type changes a field’s type to a compatible type within the same type hierarchy. The generated XSLT includes an xsi:type attribute on the element to signal the derived type. Fields with an active override are marked with a special icon in the document tree.

Steps:

1. Right-click on the field you want to override
2. Select “Override Field…” from the menu
3. Select the “Override Type” radio button in the modal
4. Choose a type from the typeahead list of compatible derived types
5. Click Save — the field tree updates to show the new type’s structure and an icon appears next to the field

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 in the document tree.

Steps:

1. Right-click on a field that has available substitutions
2. Select “Override Field…” from the menu
3. Select the “Substitute Element” radio button in the modal
4. Choose a substitute element from the typeahead list
5. Click Save — the field updates to reflect the substituted element’s name and structure

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.

Source side

All substitution candidates are rendered as children of the abstract wrapper in the tree by default — you can drag any candidate directly onto a target field without making an explicit selection first. To narrow the tree to one candidate, right-click the abstract wrapper and use “Select ‘X’ in ‘Y’” (inline) or “Select Substitute…” (modal) — the same actions as the target side. Once applied, only the selected candidate is shown.

Target side

An abstract element initially shows only the wrapper node; candidates are hidden until you make a selection. There are two ways to select a concrete implementation:

Inline quick-select — Right-click the abstract element wrapper. If the substitution group is small, the context menu lists each candidate directly with a “Select ‘X’ in ‘Y’” entry that applies the selection in one click without opening a modal.

Select Substitute modal — Right-click the abstract element and choose “Select Substitute…” to open the selection modal with the full candidate list. Type to filter, then click Confirm.

Once selected, only the chosen implementation’s fields appear in the tree. The generated XSLT references the substitution element by name.

Abstract elements in repeating fields

When the abstract field has maxOccurs>1, each instance in a collection mapping can independently reference a different substitute. Duplicate a collection mapping instance (using Duplicate from the ⋮ menu) to create a second instance and assign it a different substitute.

Identifying overridden fields

Fields with active overrides are easy to identify in the document tree:

• Override Type — Marked with an override type icon
• Substitute Element — Marked with a substitution icon

Resetting a Field Override

To restore the original schema-defined field:

1. Right-click on the overridden field (marked with an icon)
2. Select “Reset Override” from the context menu
3. The field returns to its original type or element and the icon is removed

Choice Support

Understanding xs:choice in schemas

XML Schema xs:choice defines a set of mutually exclusive element options.

On the source side, all choice members are visible as children by default — you can drag any member’s fields directly without selecting first. To narrow the tree to one member, right-click the choice wrapper and use “Select ‘X’ in ‘Y’” (inline) or “Select Member…” (modal) — the same actions as the target side. Once applied, only the selected member is shown.

On the target side, a choice wrapper initially shows only the wrapper node; member fields are hidden until you make a selection.

Selecting a choice member (target side)

On the target side, right-click the choice wrapper to make or change a selection.

Inline quick-select — when a member is already selected and visible, right-click it and select “Select ‘X’ in ‘Y’” to switch to a different member in one click.

Select Member modal — right-click the choice wrapper and choose “Select Member…” to open the selection modal. Type to filter, choose a member, then click Confirm. The selected member’s fields become visible; other members are hidden.

Choice members in repeating fields

When a choice field has maxOccurs>1, each collection instance independently selects a member. Use Duplicate from the ⋮ menu to create a second collection instance and assign it a different choice member.

Working with nested choices

The DataMapper supports nested xs: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.

Clearing a selection

To return a choice field to its unselected state:

1. Right-click on the choice field (or the currently selected member)
2. Select “Clear selection”
3. The member fields are hidden again and the field returns to its unselected state

Next Steps

• DataMapper Settings — control XML declaration output for XML target documents
• Loop Mappings — abstract and choice elements also work inside for-each and for-each-group collection scopes