How to import concept-to-concept relationships to an existing model

Save PDF

Last Updated: May 13, 2026
5 minute read

Semaphore
Documentation

Explanation

The spreadsheet importer tool allows you to import and update models without RDF using Excel spreadsheets or CSV files.

This article explains how to import concept-to-concept relationships to an existing model.

The importer cannot import every modelling object into a model. The objects it can import are:

Concepts

Concept metadata values and property values (e.g. class)

Relationships between concepts

It cannot import structural objects such as new class definitions, metadata properties, and relationship types. if you want to populate custom concept metadata and property values on import, these objects must exist in your model prior to import.

Assumptions

You have an existing model.
You have the MANAGER, EDITOR, or CONTRIBUTOR role for the model.
You have your new data formatted as a flat list.

Method

Each different relationship type that you want to create must be in its own column.

During import, if you do not specify a concept scheme or parent concept, the import process will create a new concept scheme to contain the data.

Duplicate preferred labels are assumed to be the same concept. If you want to import homographs (different concepts with the same preferred label), they must be differentiated via URI. (See helpful-hints-tips-and-tricks).

Some relationship types or properties can have multiple data values in a cell: alternative labels, metadata values, and classes. Other types must have one value only per cell.

Adding relationships to existing concepts is one of the easiest things to do with the spreadsheet importer. You only need to use the flat list data format for your spreadsheet.

Tip: When creating relationships (hierarchical or associative) to existing concepts in the model and matching on the preferred label, the importer will look for that pref label and create the relationship with the first pref label match it finds. (See helpful-hints-tips-and-tricks). Because of this, matching on preferred label will not necessarily create the relationship with the intended concept in models where there are homographs of the concept you want to create the relationship with. In those cases, you need to add either the URIs or GUIDs of those related concepts to your spreadsheet, and match on those instead.

Below are the steps for importing new concepts using the flat data format using the Geography Import example file, which you can download from this link. The instructions assume that you have imported a geography model according to either of these articles: import-new-with-flat-list or import-new-with-hierarchical-format.

The example shows the best practice of using URIs.

Data Format

Here is an example of a flat format spreadsheet used in this article.

Below are explanations for each column:

Concept Name – This column contains the labels for all the concepts that you want to update.
You will not use this column during the import.
Concept URI – This column contains the URIs of the concepts you want to update.
Updates will work best by using URI or GUID as the value to match to the original concept.
Ally of (label) – This column contains the labels for concepts that you will connect as allies to the items in the Concept Name column.
It is possible to match these by the preferred labels. However, you will not use this column during the import for this example.
Ally of (URI) – This column contains the URIs for concepts that you will connect as allies to the items in the Concept Name column.
Exports to (label) – This column contains the labels for concepts that you will connect for exporting to the items in the Concept Name column.
It is possible to match these by the preferred labels. However, you will not use this column during the import for this example.
Exports to (URI) – This column contains the URIs for concepts that you will connect for exporting to the items in the Concept Name column.

Importing into the model

It is always best to perform imports in a task instead of in the main model. If something goes wrong with the import, you can delete the task and create a new one without causing any changes to the main model.

Open your task, click to open your task menu, and click Import.
Click Import Spreadsheet, and then in the Flat List section, click Import.
In the Import Spreadsheet dialog box, drag and drop your spreadsheet file. (Alternatively, you can click and navigate to the file.)
Choose the sheet you wean to import. (In this example, choose Add Relationships.) Then click Next.
The purpose of the import is to update existing concepts. Therefore, select Import as children of an existing concept or concept scheme, but leave the input box blank.
Click Next.
Choose the default class for your concepts. If the concepts in your list belong to various classes, choose Concept. Then click Next.
Map the columns to the appropriate properties, and then click Next. The information below is for the example file in this article:
- Concept name – <nothing> (this column is for your own convenience in reading the spreadsheet, and you will not import it)
- Concept URI – URI
- Ally of (label) – <nothing> (this column is for your own convenience in reading the spreadsheet, and you will not import it)
- Ally of (URI) – associative relationship: select Ally of for the relationship, then the choose to match concepts by URI
- Exports to (label) – <nothing> (this column is for your own convenience in reading the spreadsheet, and you will not import it)
- Exports to (URI) – associative relationship: select Exports to for the relationship, then the choose to match concepts by URI
On the final screen, uncheck the Overwrite existing values box.
Click Submit.