Metadata taxonomies

Metadata taxonomies enable Box admins to define metadata hierarchies that can be reused across multiple metadata templates. With taxonomies, you can define terms that form available options and add multi-level metadata to a file. Adding taxonomy metadata to a folder is read-only and requires the API. Taxonomies help admins organize and manage their company’s metadata structures. A dynamic filter displays available options based on characters entered into the dropdown box. A taxonomy can have a depth of up to 10 levels. Check the formatting rules before submitting a CSV template. A 5-level taxonomy could include: The only place you can search, sort, or filter content based on taxonomy values is by using the search bar at the top of Files when logged in as a Box user.

​

The taxonomy picker

Box includes a self-contained taxonomy picker that allows users to select one or more values from a hierarchical or flat taxonomy directly within the Box user interface. The picker renders both flat lists and deeply nested hierarchies (up to 10 levels deep) in a single, consistent dropdown menu. For flat taxonomies, the picker shows options in a single-level view with parent paths as subtitles. For deeper hierarchies, it supports a multi-level view where users drill down level-by-level with breadcrumb navigation. Depending on the template configuration, the picker uses radio buttons for single-value selection or checkboxes for multi-select. A built-in search bar lets users search globally across the entire taxonomy or narrow results to a specific sub-branch. The picker is fully optimized for keyboard navigation and screen-reader support.

​

Create a metadata taxonomy

Admins, or co-admins who have been granted the requisite permissions to create and edit metadata taxonomies for your company, can create metadata taxonomies:

1. Navigate to the Admin Console.
2. Select Metadata.
3. Select the Taxonomies tab.
4. At the top of the taxonomies window, select New +.
5. In Taxonomy Name, type the name of your metadata taxonomy.
6. In the Build Taxonomy section, do one of the following:
   • To build your taxonomy from scratch, select Create manually and define your levels and nodes directly in the UI.
   • If you have your taxonomy in a CSV-formatted file, select Import from CSV.
   • If you do not have your taxonomy in a CSV-formatted file, select Download Template. See details of the metadata taxonomy template. Once completed, upload the file to Box using the Admin Console then select Import from CSV.
7. At the top of the window, select Save.

​

Metadata taxonomy template

This section explains how to structure and format the metadata taxonomy template CSV file to avoid import errors and ensure consistent results. The file should be submitted in CSV UTF-8 format. Importing a CSV allows you to create or modify many taxonomy terms at once. The file must include a header row so the system can map columns correctly. Each row in the CSV represents a single taxonomy node. To streamline permissions and maintain security, the CSV file must be stored in Box. Place your CSV file in a Box folder you can access, then select it during the creation process.

​

Required structure

The first row in the CSV defines the levels for the taxonomy. This is the structure of the data that you import. The values you supply in the header row are the displayed values for your end users. Make sure they are user-friendly before importing the CSV file.

​

Formatting rules

The maximum hierarchy depth supported is 10 levels. Use commas as delimiters, UTF-8 encoding, and wrap fields containing commas, quotes, or new lines in double quotes. To include a quote mark inside a quoted field, double up the quotation mark (for example, He said ""Hello""). Leave empty fields blank rather than using NULL or N/A. Rows that exactly match another row (all values in all columns are the same) are skipped during import. Only alphanumeric characters are allowed, including non-English languages as defined by the Unicode standard.

​

Validation checklist

Before importing, confirm that the file size is less than 50MB, that there are no duplicate records (duplicates are skipped), that header row values do not match any values from the next line in the file, and that no tabs or semicolons are used as delimiters.

​

Best practices

Use understandable display names and keep them concise, but with enough detail that users can find them by typing. Avoid duplicates in the CSV file — while they do get skipped, they can lead to confusion. If a taxonomy is imported incorrectly, delete it and start again.

​

Import steps

1. Prepare your CSV following the rules above.
2. Validate locally with a CSV linter or spreadsheet export to CSV.
3. Create a new taxonomy in the Metadata section of the Admin Console.
4. Check the preview and correct any minor errors. For any major issues, restart the process.
5. Confirm the import.

If you need a starter template, copy the header row from the example at the top of this page and tailor columns to your taxonomy. Alternatively, a downloadable file is available during the taxonomy import process from Admin Console > Metadata > Taxonomies.

​

Edit a metadata taxonomy

1. Navigate to the Admin Console.
2. Select Metadata.
3. Select the Taxonomies tab.
4. In the relevant taxonomy row, select the name.
5. Make the desired changes then, when complete, select Save.

​

Delete a metadata taxonomy

You can delete metadata taxonomies using the Delete Metadata Taxonomies API or by accessing the Admin Console and selecting the trash bin icon. You are prompted to provide the taxonomy’s name to confirm the deletion.

​

Delete a node

You can delete nodes prior to saving the taxonomy. Select the node you want to delete, then select the trash icon alongside the address bar and select Delete. This deletes the node along with all its sub-nodes.