> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/digital-asset-management-dam/settings/taxonomies.md).

# Taxonomies

***

A taxonomy is a hierarchical dataset made of **nodes**. Unlike tags or lists, which are flat, a taxonomy lets you categorise assets along a tree structure.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2F59PW0sQi0ywunr3pQP8W%2Ftaxomony-insert.png?alt=media&amp;token=5e822ecf-12a5-4938-ae87-cc0a23faab2b" alt=""><figcaption></figcaption></figure>

Examples:

* **Geography**: Europe > France > Paris > Eiffel Tower
* **Product category**: Women > Dresses > Model X > Navy Blue

Assets are connected to a taxonomy through the **Taxonomy node** metadata field type. Each field of this type links an asset to exactly one node of a chosen taxonomy. You can select a node at any depth of the tree — you are not restricted to the last level.

Taxonomies are designed for large datasets and can contain millions of nodes.

{% hint style="info" %}
Taxonomy content uses your project's default language. Multi-language taxonomies are not supported.
{% endhint %}

### Managing taxonomies

You will find the Taxonomy page by going to **Settings > Library > Taxonomy**. This page lists every taxonomy in your project.

<table><thead><tr><th width="200">Column</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>The taxonomy name. Click it to open the node editor.</td></tr><tr><td>Nodes</td><td>The total number of nodes the taxonomy contains.</td></tr><tr><td>Description</td><td>The optional description entered when the taxonomy was created.</td></tr><tr><td>Linked metadata field</td><td>The display name of each metadata field that uses this taxonomy. Several fields can point to the same taxonomy, in which case all names are listed. Shows — when no field is linked.</td></tr><tr><td>Actions</td><td>Hover a row to reveal the <code>...</code> menu.</td></tr></tbody></table>

Hovering over a row reveals a `...` menu with the following actions: **Rename**, **Create backup**, **Restore from backup** and **Delete**. Restore from backup only appears once at least one backup exists.

#### Creating a taxonomy

1. Click **+ New taxonomy**.
2. Enter a **Name**. This field is required.
3. Optionally, enter a **Description**.
4. Click **Create**, or press Enter.

The **Language** field is displayed for information only and is fixed to your project's default language.

Once created, the taxonomy is added to the list and its node editor opens, ready for you to add nodes.

#### Renaming a taxonomy

Select **Rename** from the row's `...` menu. The modal opens pre-filled with the current name and description. Saving updates the list immediately.

#### Backing up and restoring a taxonomy

**Create backup** takes a snapshot of all the nodes in the taxonomy at that moment.

**Restore from backup** lists your available snapshots with their date, node count and author. Select one and confirm to restore it.

{% hint style="info" %}
Restoring a backup deletes all current nodes and replaces them with the content of the snapshot. This action cannot be undone.
{% endhint %}

#### Deleting a taxonomy

Select **Delete** from the row's `...` menu.

A taxonomy that is linked to a metadata field cannot be deleted. If you attempt it, a message names the field using it. Remove the link first, then delete the taxonomy.

If the taxonomy is not linked to any field, a confirmation shows how many nodes will be removed.

{% hint style="info" %}
Deleting a taxonomy clears the metadata values of every asset pointing to one of its nodes.
{% endhint %}

### Building your tree in the node editor

Click a taxonomy name to open its node editor, where you browse and organise its nodes.

The header shows the taxonomy name and its live node count. Below it, the breadcrumb shows your position in the tree — click any level to navigate back up to it.

The **Search all nodes** bar queries the whole taxonomy, not just the level you are viewing. Results display the matching node with its full path underneath, so you can tell similar names apart. Clearing the search returns you to the level you were on.

#### Navigating and selecting nodes

Each node is displayed with a radio button:

* Click a node **that has children** to drill into that level.
* Click a node **with no children** to select it.
* Click the **radio button** of any node to select it without drilling into it.

#### Adding nodes

To add nodes at the level you are currently viewing, click **+ Add node under \[name]** at the bottom of the list. To add a top-level node, use **+ Add root node** in the header.

In the modal, type a node name and press Enter to add it. Repeat to queue as many nodes as you need, then confirm to create them all at once. Duplicate names are ignored.

Newly created nodes are briefly highlighted with a **New** badge so you can spot them in the list.

#### Editing the tree

Open a node's `...` menu, or right-click it, to access the following actions:

<table><thead><tr><th width="180">Action</th><th>Description</th></tr></thead><tbody><tr><td>Add children</td><td>Create one or more nodes underneath this node.</td></tr><tr><td>Rename</td><td>Change the node name. The slug is set at creation and cannot be changed.</td></tr><tr><td>Move to…</td><td>Move the node, along with everything beneath it, to another position in the tree.</td></tr><tr><td>Delete</td><td>Remove the node and all of its descendants.</td></tr></tbody></table>

When moving a node, browse or search the tree to pick the destination. The nodes beneath the one you are moving are not offered as destinations, as a node cannot be moved into its own branch.

{% hint style="info" %}
Deleting a node also deletes every node beneath it. This action cannot be undone.
{% endhint %}

### Importing nodes from a CSV file

For large taxonomies, you can build the tree from a CSV file instead of adding nodes one by one.

{% hint style="info" %}
CSV import is only available while a taxonomy is empty. Once it contains at least one node, the option is hidden. Updating an existing taxonomy from a CSV file is not supported.
{% endhint %}

1. Create your taxonomy, then open its node editor.
2. Open the `...` menu in the header and select **Import from CSV**.
3. Use **Download template** to get a file with the correct column headers.
4. Drag your file into the drop zone, or click to browse for it.
5. Click **Upload & Preview**.
6. Review the result, then click **Publish**.

Your file must be in `.csv` format. Its columns come in pairs — a slug and a name for each level of your tree:

<table><thead><tr><th width="200">Column</th><th>Description</th></tr></thead><tbody><tr><td><code>level_1_slug</code></td><td>The unique identifier of the top-level node.</td></tr><tr><td><code>level_1_name</code></td><td>The name of the top-level node, as displayed in the interface.</td></tr><tr><td><code>level_2_slug</code></td><td>The unique identifier of the second-level node.</td></tr><tr><td><code>level_2_name</code></td><td>The name of the second-level node.</td></tr><tr><td>...</td><td>...</td></tr></tbody></table>

Add another pair of columns for each additional level you need, following the same pattern: `level_3_slug`, `level_3_name`, and so on.

Each row describes **one complete branch** of your tree, read from left to right. Rows that share a parent repeat it, so you can always tell which branch a node belongs to from the row itself.

```csv
level_1_slug,level_1_name,level_2_slug,level_2_name,level_3_slug,level_3_name
geo,Geography,fr,France,fr-paris,Paris
geo,Geography,fr,France,fr-lyon,Lyon
geo,Geography,de,Germany,de-berlin,Berlin
```

The example above creates a top-level node named Geography, with France and Germany beneath it, Paris and Lyon under France, and Berlin under Germany. Geography and France are each created once, even though they appear on several rows.

{% hint style="info" %}
Every slug must be unique across the whole taxonomy, not just within its level. Prefixing a slug with its parent, as in `fr-paris`, is a simple way to keep them unique when the same name appears in more than one branch. Slugs cannot be changed once the nodes are created, so it is worth settling on a convention before importing a large file.
{% endhint %}

#### Reviewing the preview

After uploading, the preview shows two tabs:

* **Errors & warnings** lists anything found during validation. Errors prevent publishing. Warnings do not — the affected rows are skipped and the rest are imported.
* **Structure preview** shows the tree built from the first rows of your file, so you can check the hierarchy before committing to it.

Files above 100,000 nodes may take longer to process.

### Adding a taxonomy node field

Taxonomies become available on your assets once you create a metadata field that points to one. You will find metadata fields by going to **Settings > Library > Metadata > Assets**.

1. Click **+ Add new field**.
2. Set the **Type** to **Taxonomy node**.
3. Select the taxonomy this field should use.
4. Complete the remaining field settings and click **Add**, then **Save**.

If your project contains only one taxonomy, it is selected automatically. If it contains several, choose the one you need from the list.

{% hint style="info" %}
The **Taxonomy node** type is unavailable until at least one taxonomy exists in your project.&#x20;
{% endhint %}

For the full list of field settings, see [Assets](/digital-asset-management-dam/settings/metadata/assets.md).

### Setting a node on an asset

Taxonomy node fields appear alongside your other metadata, both in the Asset Details window and in the information sidebar. They behave the same way in both places.

When a node is attached, the field displays the last two levels of its path, for example `France › Paris`. Hover it to see the full path.

To set a value, click the field. A panel opens where you can either browse or search:

* **Browse** — click a node to open its children, and use the breadcrumb or the back arrow to move back up. Nodes that contain children show a chevron and their child count.
* **Search** — start typing to search the whole taxonomy. Each result shows the full path of the node, so you can distinguish between nodes with similar names.

Click the radio button of the node you want to apply. If the field was empty, your choice is saved straight away. If you are replacing an existing value, confirm the change as you would for any other metadata field.

Users without permission to edit metadata see the field as read-only.


---

# 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.scaleflex.com/digital-asset-management-dam/settings/taxonomies.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.