Taxonomy vs. option list

Setting up your domain model comes with a recurring question: should I use an option list or a taxonomy to represent my data? It is crucial to choose the proper data format to have a high-performing application with the required features.

This document provides best practices for you to define whether you should use taxonomies or option lists for your data model.


For more best practices on taxonomy and option list, see Option list to taxonomy migration.

Taxonomy relations

Use taxonomy relations if you meet at least one of the following conditions:

  • You have a long list of values: use taxonomies when you have an extensive list (however, we recommend you avoid exceeding 300 values). For controlled vocabulary lists containing fewer than 50 values, use option lists instead.

  • You need to set security rules based on these values: option lists cannot hold security properties. Use taxonomies when you need to apply security model rules based on values from your taxonomy. For example, Fruitful brand approvers can only approve assets from the Fruitful brand, not others.

  • You need to inherit your values: option lists can be facets in search pages but cannot inherit from your data model family tree. For example, if you have an option list in the M.ProductFamily definition, you cannot show it as a facet filter on the Products search page. It needs to be a taxonomy for it to inherit from your data model.

  • You need to keep more information than just the values: option lists cannot hold more than the value of the controlled vocabulary on itself. You can extend taxonomies with additional properties because they are schema definitions. For example, you can add a description. Option lists are not schema definitions but simple data sources without any additional properties.

  • You need a deeper hierarchy than five levels: option lists have a limitation in the number of sub-levels you can create. They can hold a simple five-level hierarchy but not more. Taxonomies have no limits in the number of hierarchy levels they can carry.

Option lists

Use option lists if you meet the following conditions:

  • You have a short list of values: use option lists for controlled vocabulary lists with fewer than 50 values. In this case, option lists are more powerful than taxonomies. Do not use taxonomies for short lists of values.

  • You need to display this data only on the detail page and the entity's Search component: if the data is only displayed directly on the entity itself, use an option list.

  • You need to set conditional visibility and conditional mandatory rules: option lists can drive conditional visibility and conditional mandatory rules for other members.

Can we improve this article ? Provide feedback