Mappings

1. Overview / Introduction

Mappings are the foundational mechanism in SBE for transforming data between external tools and the internal ontology-driven model. They provide bi-directional transformation instructions that make it possible to translate universal items into SBE models and vice versa.

This translation allows tools with diverse schemas, taxonomies, or data formats to interoperate within the unified semantic framework of the SBE platform. Once an external tool’s data is represented as a model using SBE’s ontology, it can then be mapped to any other tool, assuming that tool can structurally represent the same concept.

Mappings are configured per ontological class and exist within a partitioned, entity-set-contained architecture, making them fully modular, versioned, and context-aware.

2. Conceptual Role

Mappings enable semantic interoperability across systems by translating external representations into a shared ontological format. This allows:

Publish: Transforming universal items from an adapter into ontological models.
Refresh: Transforming SBE models back into recognizable universal items for external systems.

Without mappings, the platform would have no basis for understanding or structuring data from external tools. Mappings also ensure each transformation operation (publish or refresh) is grounded in a shared, formal specification, avoiding ambiguity or inconsistency.

3. Design Rationale

Each mapping in SBE has a strict 1:1 relationship with a single ontological clazz. The mapping defines how external representations of that clazz — referred to as universal items — are transformed to and from the internal ontology-based models.

Mappings can be defined at either:

Data Source Type level: applies globally to all data sources of that type.
Data Source level: scoped to a single tool instance and overrides the generic logic.

During the transformation process, the platform will always attempt to first find a mapping to the data source, as it is seen as more specific than a data source type mapping. If none is found, then a mapping to the data source type will be used if one is present.

Mappings are also inheritable, reflecting the class hierarchy. Inherited mappings are ignored by default and must be explicitly activated or overridden.

Mappings are sorted when checking for a match during a publish. First, they are sorted by context. All mappings in the channel’s publishing context are checked first. Any mappings for an ontology in the channel’s sub-context are checked later. Once the mappings are separated by publishing context and sub-context, they are sorted by specificity, where more ancestors = more specific. If a mapping has siblings (i.e. has the same number of ancestors), they are sorted by the number of class mappings they have for the data source and data source type in use.

When refreshing, the platform already knows the type of the model, so finding a mapping is a much easier task. The platform will first check if there is a mapping for the model’s type (referred to as its origin). If a mapping is not found, it will move up the origin’s ancestor lineage to attempt to find a mapping. This is how the platform can deal with down-casting when necessary between multiple external systems.

Mappings are structured around four core components:

Class Mappings

Clazz mappings are responsible for classifying universal items during a publish. Each mapping contains a list of rules that must all be satisfied for the mapping to apply.

Rule Types for Class Mappings

Each rule must evaluate as true for the mapping to be applied (conjunctive logic). Any parameter in a rule that is optional will not be included in the evaluation if left blank. Rule types include:

HAS_SHAPE
Checks whether the universal item contains a specific shape ID.
- shapeId (Name of the shape being mapped)
- type (Optional, type of the shape being mapped)
- order (Optional, order of the shape being mapped)
CHECK_ATTRIBUTE_VALUE
Validates that the universal item contains an attribute with a specific value.
- shapeId (The shape containing the attribute being evaluated)
- attributeName (The name of the attribute being evaluated)
- attributeValue (The expected value of the attribute)
IS_ATTRIBUTE_EMPTY
Passes if the universal item either does not contain the specified attribute or the attribute has no value.
- shapeId (The shape containing the attribute being evaluated)
- attributeName (The name of the attribute being evaluated)
IS_ATTRIBUTE_PRESENT
Passes if the universal item contains the specified attribute, regardless of value.
- shapeId (The shape containing the attribute being evaluated)
- attributeName (The name of the attribute being evaluated)
HAS_ATTRIBUTE_WITH_DATATYPE
Checks that a given attribute has the expected data format and type.
- shapeId (The shape containing the attribute being evaluated)
- attributeName (The name of the attribute being evaluated)
- format (The expected format of the attribute)
- type (The expected type of the attribute)

Shape Factories / Mapped Shapes

Used during refresh, shape factories assign shape IDs and default values to universal items to help the adapter re-identify the item. Defaults can be overridden by model data.

Property Mappings

Used to map attributes between the universal item and the model.

On publish: external → ontological
On refresh: ontological → external

Each mapping supports type and format checks and is split by data source / source type.

Relation Mappings

Transform links in both directions:

On publish: relation name → ontological relation
On refresh: model link → relation name

Mappings for relations also support inheritance and context-aware overrides.

4. Relationship to Other Resources

Relationship to Clazzes

Mappings are linked to a single class. If a class is updated or deleted, its mapping (and children) are automatically updated or removed.

When a class is updated — for example, when property specs or relation specs are changed — these updates are automatically reflected in all descendant classes. Corresponding mappings for those descendants will also reflect the updated property or relation specs inherited from their parent class.

Relationship to Partitions and Entity Sets

Mappings reside in entity sets, which are contained within partitions. This structure enables scoped deployment and versioning.

Relationship to Channels and Publishing Context

Each channel’s publishing context comes from the ontology entity sets in its attached model entity set’s context. This context — and any recursively linked entity sets — defines the mappings used in transformation.

Mappings in the immediate context are evaluated first. Inherited ones are evaluated afterward.

5. Conceptual Usage Patterns

Mappings are authored per class and per (data source, data source type) pair.

Inheritance and Mapping States

Mappings support inheritance through the class hierarchy. When a mapping is created for a child class, all applicable mappings from ancestor classes are inherited and made locally available.

Each mapping exists in one of four states:

Local: Defined directly on the class.
Inherited: Pulled from a parent class and unchanged.
Overridden: Modified inherited mapping.
Ignored: Present but excluded from transformations.

All inherited mappings are set to Ignored by default. This opt-in approach prevents unintended transformations from unrelated tools being applied to the child class.

Only Local, Inherited (active), and Overridden mappings are used in publish/refresh. Ignored mappings are visible but not executed.

Diffs and Mapping Forks

Mappings are a diffable resource in SBE, supporting advanced workflows like forking and merging.

A fork creates an independent copy of a mapping that can evolve separately. Mappings are forked when an ontology is forked.
Both the original and the fork can be independently versioned and life-cycled.
The original and forked mappings can be diffed to display the difference between the two versions. The diff can also be applied to either the original or forked mappings.

Diffable Components

There are four main components of a mapping that are compared during a diff:

Class Mappings – Conditions that determine applicability during publish.
Mapped Shapes – Shape factories used in refresh to assign identities and defaults.
Mapped Properties – Attribute-level transformation logic.
Mapped Relations – Link transformation logic across models.

Diffs are grouped and displayed per data source/data source type, so each mapping segment is clearly scoped by its integration target.

Three-Way Merge Support

SBE also supports three-way diffs, which help identify merge conflicts and guide resolution:

The system tracks the base version — the state of the mapping at the time of fork or last merge.
A conflict arises when both the source and destination mappings have diverged from that base in different ways.
Users can resolve conflicts via the diff UI by choosing to:
- Accept: Apply the left-hand (source) value to the right-hand (destination).
- Reject: Leave the destination unchanged, skipping that change.
- Revert: Reset the destination value back to the original base version.

6. Common Pitfalls, Misunderstandings and Troubleshooting

Missing Mappings = Deletion: Previously tracked but now unmatched items are removed during refresh or publish.
Non-Isomorphic Mappings Are Immutable: Once used in a channel, modifying a non-iso mapping risks corrupting model data.
Overuse of Complex Rules: Rule complexity introduces fragility.
Inheritance Misuse: Inherited mappings default to IGNORED.
Matching Ambiguity: Immediate context takes priority over inherited ones.

💡 Tip: The Transformer Remarks can be found in the Tracking UI, under the "Detailed Logs" of each publish or refresh. These logs show:
Unmapped properties or relations
Non-isomorphic transformation behavior
Why items failed to match a mapping
Raw SBE models and universal items (for reverse engineering)

Publish

Models

Confirm active mapping for origin reference
Validate class mapping rules
Check clazz hierarchy

Properties

Ensure all required external attributes are present
Match attribute names and types
Fill in required values or defaults

Links

Check relation names match
Confirm link targets are published
Ensure source scoping is correct

Refresh