# Taxonomies

Learn more about working with taxonomies, which can be used to define hierarchical structures for content classification.

## Overview

A taxonomy is a group of terms arranged in a hierarchical structure. The primary purpose of a taxonomy is to classify and logically connect related content items using a more elaborate structure than [enumerations](https://hygraph.com/docs/developer-guides/schema/using-enumerations). This helps with content management and improves user experience with enhanced searchability.

**Note:**
Taxonomies are an enterprise feature. [Contact our sales team for access](https://hygraph.com/contact).

## How it works

1. The developer or the administrator defines the taxonomy in the schema using hierarchical tags.
    - Example: `Clothes → Men → Pants → Formal`
2. The developer or the administrator adds the taxonomy to a model.
3. While creating content based on the model, the content team classifies content using one of the predefined terms in the taxonomy.

## Benefits of taxonomies

- Your end users can find and filter content easily.
- Your content is well-organized and well-structured in your content management system.
- You can dynamically classify content for search, filtering, and personalization purposes. For example, a user could search for full-sleeve formal shirts or full-sleeve shirts. If the user is looking for a full-sleeve shirt, they would be shown both formal and casual shirts. Depending on the parent-child relationships you’ve set up, your options to dynamically classify content are limitless.

## Permissions

Here, are the permissions given to the default roles in Hygraph:

| Role                        | Permissions                                         |
|-----------------------------|-----------------------------------------------------|
| Admin                       | <ul><li>Create, read, update and delete a taxonomy. </li><li>Create, read, update and delete taxonomy nodes.</li></ul> |
| Developer                   | <ul><li>Create, read, and update a taxonomy. </li><li>Create, read, update and delete taxonomy nodes.</li></ul> |
| Editor                      | <ul><li>Read a taxonomy. </li><li>Create, read, and update taxonomy nodes.</li></ul>          |
| Contributor                 | <ul><li>Read a taxonomy. </li><li>Read taxonomy nodes.</li></ul>                              |

## Create a taxonomy

[Video: Create a taxonomy](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdinb5ej3jd007vybggpiup3)

1. Navigate to the **Schema** builder.
2. In the Schema list, click **+ Add** next to Taxonomies. Or, if you're adding a taxonomy for the first time in the project, click **Taxonomies**, and then click the **+ Add Taxonomy** button located at the center of the screen. The **New Taxonomy** screen is displayed.
3. Provide a **Display name**. This is the name of the taxonomy that is displayed in Hygraph. The **API ID** field is autogenerated as you enter the **Display name**, but you can edit this value. The API ID is used to access this taxonomy through the API.
4. Optionally, you can add a **Description**.
5. Click **Add Taxonomy**. Now, the **Nodes** tab is displayed. This tab displays the parent-child relationships defined in this taxonomy.
6. The `Display name` of the taxonomy is available as the root node name. To modify this, hover over the root node, click **...** (context menu), and then click **Rename node**.
7. To add a child node to the root node, hover over the root node, and click **Add child node**. Provide a name, and click **Add**. The `API ID` is autogenerated as you enter the name. This ID is used to access the taxonomy node through the API.
  - You cannot have duplicate node or API IDs in the same taxonomy.

Repeat this step to create multiple parent-child relationships between the different nodes.

## Add a taxonomy to a model

[Video: Add taxonomy to a model](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdio8diu510d07w0fmb4q4f7)

1. Navigate to the **Schema** builder.
2. Select the model you wish to add the taxonomy to.
3. From the **Add fields** right sidebar, select the **Taxonomy** field.
4. Complete the `Display name` field. This autogenerates the `API ID` field, but you can edit this value if you want.
5. Use the `Taxonomy` dropdown to select the taxonomy you want to add to this model.
6. Optionally, you can also add a `Description`.
7. This screen allows you to control different properties of your **Taxonomy** field: you can allow multiple values by selecting the checkbox under the `Field options` section.
8. Click `Add` to save.

After you add a taxonomy to your model, it is available for use in the Content Editor.

## Use demo taxonomy

1. Navigate to the **Schema** builder.
2. If you're adding a taxonomy for the first time in the project, click **Taxonomies**, and then click the **Add demo taxonomy** button located at the center of the screen.
3. The system generates the demo taxonomy and displays the taxonomy nodes.

## Modify a taxonomy

[Video: Modify a taxonomy](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdit5yj0atyz07vyad07cprq)

1. Navigate to the **Schema** builder.
2. Under **Taxonomies**, select the taxonomy that you want to modify.
3. On the **Nodes** tab, you can do the following:

    | Task                      | How to do it                         |
    |-----------------------------|------------------------------|
    | Add a child node            | Click **Add child node** next to the node. |
    | Edit name of existing node  | Click <img src="/images/docs/developer-guides/edit.png" class ="inline"></img> to update the name of the node.  |
    | Move node to a new parent   | Click <img src="/images/docs/developer-guides/move.png" class ="inline"></img> and select a new parent from the list of existing nodes.  |
    | Delete the node             | Click <img src="/images/docs/developer-guides/delete.png" class ="inline"></img> to delete the node. You cannot delete a taxonomy node, if it is used in a content entry. |

4. On the **Settings** tab, you can modify the display name and the API ID of the taxonomy, and add or update the description, if needed.

## Delete a taxonomy

[Video: Delete a taxonomy](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmdixo0ywggbo07w0wommbob0)

1. Navigate to the **Schema** builder.
2. Select the taxonomy you want to delete.
3. Click **...** (context menu), and then **Delete** to delete the taxonomy.

## Related docs

- [Best practices for taxonomies](https://hygraph.com/docs/developer-guides/schema/taxonomies-best-practices) - Recommended strategies for designing and maintaining taxonomies.
- [API reference for taxonomies](https://hygraph.com/docs/api-reference/schema/taxonomies) - API reference document on fetching taxonomy and taxonomy nodes.
- [Filter taxonomies using the Content API](https://hygraph.com/docs/api-reference/content-api/filtering#taxonomy) - How to filter taxonomies using the Content API.
- [Filter taxonomies in the content table](https://hygraph.com/docs/editor-guides/content/filter-content#taxonomy) - How to filter entries by taxonomies in the content table.