Skip to main content

Message mappings

Message mapping specifications provide a way to create one-directional alignments between two message models. They allow you to document how elements from one message relate to elements in another message, which is essential for interoperability and data transformation scenarios.

Message mappings are particularly useful when you need to:

  • Document how data from one standard maps to another
  • Enable data transformation between different message models
  • Compare and align specifications from different domains or organizations
  • Track the relationship status between elements across specifications

Creating a message mapping specification​

To create a message mapping specification:

  1. Navigate to the Specifications screen
  2. Click the '+' icon in the top right corner
  3. Select Mapping from the dropdown menu

Add specification menu

This will create a new message mapping specification. Like other specification types, you'll need to:

  • Fill in the general specification fields (name, title, project, description, etc.) as described in Manage specifications
  • Create a specification version to hold the actual mapping content

Configuring the message mapping​

After creating a message mapping specification and version, you can configure the mapping by editing the version. The Mapping tab allows you to specify:

  • Source message: The message model that you want to map
  • Target message: The message model you want to map the source onto

Both source and target must be message models in your Semantic Treehouse environment.

The mapping configuration screen also includes standard tabs for version management, release notes, documentation, and acknowledgements, as described in Manage specifications.

Creating element mappings​

A message mapping consists of several element mappings describing which elements from the source and target message relate to each other, and how.

Element mappings can be created and managed through the canvas interface when viewing a message mapping. The canvas provides a visual representation of the mapping, showing:

  • The source and target message models
  • All element mappings between them
  • Progress indicators showing mapping status
  • Search and filtering capabilities

Switch the mapping to edit mode, then drag an element from the source message to the target message to create an element mapping.

Element mapping properties​

Each element mapping has several properties that describe the relationship:

Status​

The status indicates the current state of the mapping:

  • Final: The mapping is complete and verified
  • Proposal: A suggested mapping that requires discussion
  • Missing Info: The mapping needs additional information to be completed

Predicate​

The predicate describes the type of relationship between the source and target elements, using SKOS (Simple Knowledge Organization System) vocabulary:

  • skos:exactMatch (=): The elements can be used interchangeably with high confidence
  • skos:closeMatch (≈): The elements are sufficiently similar to be used interchangeably in some cases
  • skos:broadMatch (⊂): The source element relates to a more generic concept in the target
  • skos:narrowMatch (⊃): The source element relates to a more specific concept in the target
  • skos:relatedMatch (~): An associative relationship between the elements
  • custom:noEquivalent (≠): No equivalent exists in the target (explicit 1:0 mapping)

Justification​

The justification indicates how the mapping was created or determined:

  • semapv:ManualMappingCuration: A human expert manually reviewed and created this mapping
  • semapv:LexicalMatching: Based on string/label similarity (e.g., "Invoice" matches "Invoice")
  • semapv:LogicalReasoning: Inferred through ontology reasoning or inference rules
  • semapv:SemanticSimilarityThresholdMatching: Automated semantic analysis (e.g., embeddings, machine learning, or LLM-based matching)

Annotations​

Annotations provide additional context or notes about the mapping. You can add multiple annotations to document:

  • Differences between the elements
  • Transformation rules or considerations
  • Usage notes or constraints
  • Any other relevant information about the mapping relationship