Syntactic Mapping

Overview

A Syntactic Mapping (aka. Schema Mapping, Ontology Mapping) defines how the structure of a local source dataset—including its tables, columns, and field types—should be transformed to conform to a target data model, such as OMOP or FHIR.

In the Rhino Data Harmonization Engine (DHE), AI-assisted recommendations and human review are used to define these transformations, which can incorporate existing Semantic Mappings and ultimately be used to generate a Data Harmonization ETL.

Use this when: You need to map source columns to target columns, change data types or formats, combine fields, apply logic during transformation, or apply a semantic mapping as part of the transformation.

Note: When defining a Syntactic Mapping, you will always be working with source and target schemas, rather than individual datasets. This allows a Syntactic Mapping to be reusable across multiple datasets that share the same schemas, rather than being tied to specific data.

---

Accessing Syntactic Mappings

To access the Syntactic Mappings page:

1. Select Data Mappings from the main menu.

2. In the Data Mappings page, select the Syntactic Mappings tab.

The Syntactic Mappings tab shows all the active syntactic mappings that have been created.

To search for a syntactic mapping, use the Seach Syntactic Mapping text box located at the top right corner of the page.

The fields in the screenshot above are defined in the table below.

Button or Field	Description
Create Syntactic Mapping	Click this button to create a new syntactic mapping.
New version	Click this button to create a new version of an existing syntactic mapping.
Syntactic Mapping Name	Name of the mapping.
Version	Indicates the version of the Syntactic Mapping. The first version of a Syntactic Mapping is the number 0.
Information icon (on hover)	Displays additional information about the syntactic mapping, such as the description provided during creation of the syntactic mapping.
Date Created	Indicates the date the syntactic mapping was created.
Target Data Model	Indicates the target data model for the mapping, such as OMOP v5.4.
Source Data Schemas	Indicates the source data schemas of the datasets that you would like to map. If there is more than one, the number of source schemas will appear (e.g. “3 Schemas”). If there is more than one schema, hover to see the names of the schemas.
Target Tables	Indicates the target tables for the transformation. If there is more than one, the number of target tables will appear (e.g. "2 Tables"). If there is more than one table, hover to see the names of the tables.
Creator	Name of the person who created the syntactic mapping.
3 Dot Menu	The three dot menu (also known as the "context menu") provides access to additional options: Copy UID, Show Configuration, Download Mapping Config, and Remove Syntactic Mapping.

---

Creating a New Syntactic Mapping

Prerequisites

• You must have the "Manage Data Mappings" permission.

• The dataset that you want to harmonize must have been imported into FCP.

1

Enter the mapping details

In the Syntactic Mappings page, select Create Syntactic Mapping.

The Create Syntactic Mapping page appears.

Enter the name of the syntactic mapping.

Optionally, enter the description of the syntactic mapping.

We encourage you to provide as detailed a description as possible, as this additional context helps the LLM generate more accurate and relevant recommendations.

Select the Target Data Model from the drop down menu.

Options are:

• OMOP v5.4

• FHIR R4 — a second dropdown appears for Target Data Model Version: choose FHIR R4 IL Core or FHIR R4 IL HDP.

• Custom — use for any non-standard or internal data model.

2

Configure

You can either create the configuration via the UI or upload a configuration from a file (in JSON format).

Manually Configure

To create the configuration in the UI, click Manually Configure, then select the source data schema(s) from the drop-down menu under Source Data Schemas. You can select more than one. Next, select the Target Table(s) from the drop down menu. You can select more than one.

For FHIR R4 IL HDP, there are 20 tables (also called profiles) available: IL Core Device, IL Core Encounter, IL Core Immunization, IL Core Procedure, IL HDP Allergy Intolerance, IL HDP Condition, IL HDP Device Dispense, IL HDP Device Request, IL HDP Document Reference, IL HDP Medication, IL HDP Medication Administration, IL HDP Medication Dispense, IL HDP Medication Request, IL HDP Medication Statement, IL HDP Observation Lab, IL HDP Organization, IL HDP Patient, IL HDP Practitioner, IL HDP Service Request, IL HDP Vital Signs. For more information on these tables, see this link.

Upload from File

To upload a configuration from a file (supported for all target data models), click Upload from File, then click or drag and drop a JSON file into the shaded area or select "Browse" to select a JSON file from your computer. Once uploaded, the name of the file will appear.

3

Create the mapping

Click Create Syntactic Mapping.

Your new mapping appears in the Data Mapping page under the Syntactic Mappings tab.

---

Editing a Syntactic Mapping

Once you have created the syntactic mapping, you can review and edit the mapping from source to target fields, and their associated transformations.

Prerequisites

• You must have the "Manage Data Mappings" permission.

• The dataset that you want to harmonize must have been imported into FCP.

• The syntactic mapping you want to edit must already exist.

Steps

1

Open the mapping

Click on the syntactic mapping in the Syntactic Mappings page. The Edit Syntactic Mapping page appears.

If you created a new syntactic mapping and selected to manually configure it in the UI, then you will automatically be brought to this page to set up your new syntactic mapping.

2

Review the target fields

All target tables for the syntactic mapping and their fields appear in the Target Field column. A red asterisk indicates that the target field is required.

3

Map source fields

For each target field, you can select one or more source fields to map to the target field. Click on the source field dropdown and you can select fields from any input data schemas for the syntactic mapping. If you select more than one field, make sure that you select fields from the same schema, and note that you will be required to configure a transformation to define how to generate the value for the target field from the different source fields.

4

Edit transformations

You can edit the transformations each target field by clicking the pencil icon in the Transformations column.

5

Save your work

At any time, you can click the Save button to save your work. Syntactic Mappings can be updated as you work through the different source to target field mappings and transformations.

Once you run a Rhino Data Harmonization (RhinoDHE) Code Object that references a Syntactic Mapping, it can no longer be edited (to ensure reproducibility), and you must create a new version of the Syntactic Mapping to continue editing it.

---

Reviewing Syntactic Mapping Recommendations

The Rhino FCP can auto-generate syntactic mapping recommendations and their associated transformations using AI to speed up the initial mapping process. After the suggested recommendations are made, you can review and adjust them as necessary.

Prerequisites

• The syntactic mapping must already be created using "Custom" as the target data model.

• If a Rhino Data Harmonization (RhinoDHE) Code Object references syntactic mapping, it must not have been executed (run). If it has, the mapping can no longer be edited (to ensure reproducibility). If that has happened, create a new version of the Syntactic Mapping to continue editing it.

Note: Make sure the Description field is populated for each field in both your source and target schemas. These descriptions provide important context to the LLM when generating mapping recommendations. Without them, the LLM may not have enough information to generate the Syntactic Mapping successfully.

Steps

1

Review Source & Target Fields

In the Syntactic Mappings page, the Source Fields appear in the Source Fields column. All target tables for the syntactic mapping and their fields appear in the Target Field column. A red asterisk indicates that the target field is required.

2

Generate recommendations

Select the "Generate Recommendations" button in the top right section of the screen to suggest source mappings for the target field automatically. A pop up note appears in the bottom right corner of the screen indicating that recommendations are being generated. While recommendations are being generated, you can go to other screens in Rhino FCP to work.

3

Review the AI output

When the recommendations have been made, review each field to determine the accuracy of each mapping. AI recommendations have icons next to them to indicate that a row was populated by AI. The icon disappears after a user edits and saves changes. Note that some rows will be populated with recommendations, while others might not be.

4

Handle errors

When AI fails to generate relevant recommendation, an error message appears on the corresponding row.

5

Make manual changes

Make changes to mappings manually if needed. As you do this, click the Save button to save your work. Syntactic Mappings can be updated as you work through the different source to target field mappings and transformations.

6

Review transformations

Review and address transformations as well.

7

Regenerate if needed

If needed, you can choose to generate LLM recommendations again. The fields that you already populated will remain as is and the LLM will generate recommendations for remaining fields only.

NOTE: If you need to start all over again, select the "Clear All" button at the top right corner of the screen, then select Remove all Mappings in the message that appears. If you do this, it will clear all current mappings and reset the table, so proceed with caution. This change cannot be undone.

---

Creating a New Syntactic Mapping Version

Before you create a new version, it is helpful to understand that when a new version is created, the system uses the most recent existing version of the same Syntactic Mapping for preservation.

The following table shows the schema change and the user interface behavior in the new version.

Field	Description
Schema Change	User Interface Behavior in the New Mapping Version
Unchanged Target or Source Fields	Previously defined Source Fields and Transformations are preserved. You can edit preserved mappings as needed.
New Target Fields	Appear as empty, editable rows in the Syntactic Mapping panel, ready for you to define a new mapping.
New Source Fields	Become available in the Source Field selection dropdowns.
Deleted or Renamed Target Fields	Corresponding mapping rows are removed and will not be displayed in the new version.
Deleted Source Fields	Mappings referencing these fields are cleared, and the affected rows will appear empty and editable if the Target Field still exists.

• Preservation Logic: Mappings are preserved only when the Target Field exists in the new Target Schema version AND all referenced Source Fields exist in the new Source Schema version.

• Matching: Field preservation requires an exact match on the field name.

• Scope: Preservation applies only within the same Syntactic Mapping object; it does not support copying mappings between different mapping objects.

• No Automatic Remapping: No automatic or heuristic remapping is performed for renamed fields. If a field is renamed, the mapping is cleared or removed, ensuring you explicitly review and redefine any mappings where schema semantics have changed.

Steps

1

Open the new version flow

In the Syntactic Mapping page, click the New Version button of the Syntactic Mapping you want to create a new version of.

2

Review the version details

The Create New Syntactic Mapping Version page appears.

3

Keep required fields unchanged

The name and target data model cannot be changed - they must be consistent for all versions of the same Syntactic Mapping. If you would like to select a different name or target data model, you can create a new Syntactic Mapping instead of creating a new version.

4

Update the description

The description can be updated. Update it to indicate changes, if desired.

5

Update source data schemas

Update the source data schemas if needed. For more information on how to do this, see the Creating a Syntactic Mapping article.

6

Update target tables

To streamline data harmonization when Source and Target Schemas evolve (e.g., due to regulatory updates or new source data), Syntactic Mapping definitions are automatically preserved. This feature allows you to focus only on mapping new or changed fields (schema deltas) without redoing your completed work. Update the target tables if needed. For more information on how to do this, see the Creating a Syntactic Mapping article.

7

Create the new version

Click the Create New Version button. The new version of the syntactic mapping appears on the Syntactic Mappings page.

---

Removing a Syntactic Mapping

Prerequisites

• You must have the "Manage Data Mappings" permission.

• The syntactic mapping must exist.

Steps

1

Select the mapping you want to remove

Go to Data Mappings → Syntactic Mappings

On the Syntactic Mapping page, select the three-dot menu for version of the syntactic mapping you want to remove.

2

Select the option to remove syntactic mapping

Select “Remove syntactic mapping”.

A message will appear indicating that the mapping has been removed.