> For the complete documentation index, see [llms.txt](https://docs.rhinofcp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rhinofcp.com/data-harmonization/syntactic-mapping.md).
# 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.
{% hint style="info" %}
**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.
{% endhint %}
{% hint style="warning" %}
**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.
{% endhint %}
***
## 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.
{% stepper %}
{% step %}
#### 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.
{% hint style="info" %}
We encourage you to provide as detailed a description as possible, as this additional context helps the LLM generate more accurate and relevant recommendations.
{% endhint %}
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.
{% endstep %}
{% step %}
#### Configure
You can either create the configuration via the UI or upload a configuration from a file (in JSON format).
{% tabs %}
{% tab title="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](https://simplifier.net/hdp-il).
{% endtab %}
{% tab title="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.
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
#### Create the mapping
Click **Create Syntactic Mapping**.
Your new mapping appears in the Data Mapping page under the Syntactic Mappings tab.
{% endstep %}
{% endstepper %}
***
## 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
{% stepper %}
{% step %}
#### Open the mapping
Click on the syntactic mapping in the Syntactic Mappings page. The **Edit Syntactic Mapping** page appears.
{% hint style="info" %}
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.
{% endhint %}
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### Edit transformations
You can edit the transformations each target field by clicking the pencil icon in the Transformations column.
{% endstep %}
{% step %}
#### 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.
{% hint style="info" %}
**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.
{% endhint %}
{% endstep %}
{% endstepper %}
***
## 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.
{% hint style="warning" %}
**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.
{% endhint %}
#### Steps
{% stepper %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### Handle errors
When AI fails to generate relevant recommendation, an error message appears on the corresponding row.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### Review transformations
Review and address transformations as well.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
**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.
{% endhint %}
***
## 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
{% stepper %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### Review the version details
The Create New Syntactic Mapping Version page appears.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### Update the description
The description can be updated. Update it to indicate changes, if desired.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### Create the new version
Click the Create New Version button. The new version of the syntactic mapping appears on the Syntactic Mappings page.
{% endstep %}
{% endstepper %}
***
## Removing a Syntactic Mapping
#### Prerequisites
* You must have the "Manage Data Mappings" permission.
* The syntactic mapping must exist.
#### Steps
{% stepper %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### Select the option to remove syntactic mapping
Select “Remove syntactic mapping”.
A message will appear indicating that the mapping has been removed.
{% endstep %}
{% endstepper %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.rhinofcp.com/data-harmonization/syntactic-mapping.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
