> 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/semantic-mapping/custom-vocabularies.md).

# Custom Vocabularies

## Overview

A **custom vocabulary** is a user-defined set of standardized terms or concepts that can be used as mapping targets when an existing standard vocabulary, such as those provided by OMOP, does not meet your needs.

For example, if your organization uses its own classification system for procedures, you can create a custom vocabulary containing those terms and then use **Semantic Mapping** to map values from your source datasets to the appropriate custom terms.

Your custom vocabulary can contain up to 1 million entries.

{% hint style="info" %}
**Use this when**: your data requires a vocabulary beyond Rhino FCP's built-in options (e.g., OMOP, FHIR).
{% endhint %}

***

## Accessing Custom Vocabularies

To open the **Custom Vocabularies** page, complete the following steps.

1. Select **Data Mappings** from the Main Menu. The **Data Mappings** page appears.
2. Select the **Custom Vocabularies** tab. The **Custom Vocabularies** page appears. To search for a custom mapping, use the Search Custom Map text box located at the top right corner of the page.

![](https://content.gitbook.com/content/ydySyCBmy6F7NnGn4bPa/blobs/stgwvfdXEMyKLDSVNdXX/35166537597597)

The table below defines each field in this page.

|                        |                                                                                                                                               |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Field**              | **Description**                                                                                                                               |
| Custom Vocabulary Name | Name of the custom vocabulary name, such as “Encounters” or “Billing Codes”.                                                                  |
| Version                | Version of the custom vocabulary. This increments each time you make a change to the custom vocabulary.                                       |
| Date Created           | Date the mapping was created.                                                                                                                 |
| # of Terms             | Number of terms for this custom vocabulary.                                                                                                   |
| Creator                | Name of the person who created the mapping.                                                                                                   |
| Status                 | Status of the Custom Vocabulary                                                                                                               |
| Three-Dot Menu         | The three-dot menu (also known as the “context menu”) provides access to additional options: Copy UID, Show Configuration, Remove Vocabulary. |

***

## Creating a New Custom Vocabulary

{% stepper %}
{% step %}
In the **Data Mapping > Custom Vocabularies** page, click **Create Custom Vocabulary**.
{% endstep %}

{% step %}
The **Create Custom Vocabulary** page appears.

![](https://content.gitbook.com/content/ydySyCBmy6F7NnGn4bPa/blobs/EjmhxEnmHQdRHU6xdutz/30455864515997)
{% endstep %}

{% step %}
Enter a name for your vocabulary and optionally add a description.
{% endstep %}

{% step %}
You can either manually enter terms for your vocabulary or upload a file that contains the terms. 

Note that there are **two supported formats** for the terms that you enter (or upload):

* **Codes and Terms:** if you have terms that have specific codes (e.g. "C01" for "Approved" and "C02" for "Denied"), enter the codes and the terms in CSV format or manually, with a comma separating between the code and the term. Each term should be entered on a different line. For example:

  ```auto
  C01,Approved
  C02,Denied
  ```
* **Terms-only (without codes)**: If you have terms that don't have special codes, then you can enter each term on a separate line. For example:

  ```auto
  Approved
  Denied
  ```

{% hint style="warning" %}
In both cases, any commas in your term display text should be escaped using a slash (\\).\
Do not include a header row.
{% endhint %}

**Uploading a file**

* Select Upload File button on the Create Custom Vocabulary page.
* Upload a comma delimited (CSV) file from your device by clicking the Upload File button. Do not include a header row. Each term should be entered on a different line. If you have terms with specific codes, separate them with commas.
  {% endstep %}

{% step %}
When complete, click **Create Custom Vocabulary**. The page closes and the custom vocabulary page is displayed, with an entry for the vocabulary that you just created.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Once you've created a custom vocabulary, you can use [Creating a New Semantic Mapping](https://app.gitbook.com/o/SKrkLtXReIPmOZjXnWZA/s/ydySyCBmy6F7NnGn4bPa/~/edit/~/changes/333/data-harmonization/semantic-mapping#creating-a-new-semantic-mapping) to map values from a dataset field to entries in your custom vocabulary.
{% endhint %}

***

## Editing a Custom Vocabulary

#### Prerequisites

* You must have the "Manage Data Mappings" permission.
* A custom vocabulary must have already been created.

#### Steps

To edit an existing custom vocabulary, you will need to [remove it](#removing-a-custom-vocabulary), then create it again with the updated terms.

***

## Removing a Custom Vocabulary

#### Prerequisites

* You must have the "Manage Data Mappings" permission.
* A custom vocabulary must have already been created.

{% hint style="warning" %}
You cannot remove a custom vocabulary while semantic mapping recommendations are being generated.
{% endhint %}

#### Steps

1. In the **Data Mappings > Custom Vocabularies** page locate the custom vocabulary you want to remove.
2. Click the three-dot (meatball) menu at the end of the entry and select **Remove Custom Vocabulary**.
3. When prompted about removing the vocabulary, select **Yes**.
4. The vocabulary is removed.

{% hint style="info" %}
After removing a custom vocabulary, any Semantic Mappings associated with this vocabulary will also be removed.
{% endhint %}


---

# 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/semantic-mapping/custom-vocabularies.md?ask=<question>&goal=<endgoal>
```

`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.