#Best practices for taxonomies
Taxonomies are hierarchical, centrally managed vocabularies that classify content across multiple models. Taxonomies include consistent labels that improve findability, search and filter UX, personalization, and governance.
#When to use taxonomies
Use taxonomies when you need:
- A shared classification system reused across multiple models, such as a Blog, Product, Case study, Event
- A hierarchy of terms. We recommend 3 nesting levels. Example:
Root → Category → Subcategory → Topic- Hygraph supports up to 6 nesting levels, not counting the root.
- Consistent editorial language when terms change rarely.
- Filters in apps and custom views.
Currently, you cannot localize taxonomy fields in Hygraph. For locale‑specific category trees that diverge per language, you have two options:
- Same structure, but different labels: Keep one taxonomy, and map term IDs to localized labels in your app or a helper model.
- Different structures per locale: Create separate taxonomies, such as
Category_EN,Category_DE, or use a localized Category model with references.
#When not to use taxonomies
We recommend that you do not use taxonomies in the following scenarios:
| Need | Use |
|---|---|
| Entity with fields or metadata on the nodes. Model lifecycle, validation, and localization may apply. For example, you want additional information such as logos, descriptions, links, country codes, SEO, and so on. | Model and reference |
| The values are per‑entry, ad‑hoc, or dynamic. For status, type, or flags, a small, closed, dynamic set of values is useful. | Enumeration |
| Navigation or menus that need ordering, audience rules, or content per node, compose into models. Optionally, mirror high‑level menu groups in a taxonomy only if you need to use filters. | Model and component |
| Complex relationships or additional business logic. For example, creating a Compatibility taxonomy with nodes for each product and tagging Product A with Product B implies "A is compatible with B". This duplicates your products inside the taxonomy and does not let you capture details like "since version 2.0", "only in Europe", or "one-way vs. two-way compatibility". | References (possibly with a join model) |
#Decision flowchart
Taxonomy decision flowchart
Create a taxonomy only if your answer is YES to the following questions:
- Will the labels be reusable? Is this a vocabulary that should be centrally managed? Taxonomies are especially useful if reused across models, but even within a single model, they’re the right choice when you need a hierarchy rather than an enumeration.
- Do the labels need to be hierarchical? Do we benefit from parent-child grouping?
- Will the labels be stable?
If you answered No to any question, consider the following modeling options:
- No to Question 1 → Enumeration or model-specific field
- No to Question 2 → Enumeration or a flat reference model
- No to Question 3 → Enumeration or string
#Taxonomy patterns
A high-level overview of the taxonomy patterns:
- Up to three nesting levels (excluding the root) – Recommended for most use cases.
- Four to five nesting levels - Use only when following external standards or justified by customer requirements.
If your taxonomy goes deeper without clear justification, you are possibly introducing other dimensions, such as audience, format, or region. Rather than extending a single hierarchy, you can model these as enumerations, additional taxonomies, or references.
#Flat taxonomy
A flat taxonomy, Root → Child, means everything sits one level below the root. This is possible, but it works like a long enumeration. Use this option only when you know you will expand this into a hierarchy later. Avoid placing a large number of siblings directly under the root, as this significantly reduces editor usability.
#Two-level taxonomy
A two-level taxonomy, Root → Parent → Child, is the most common structure. Example: Root → Industry → Sub-industry or Root → Category → Subcategory. This approach provides editors with a clear structure while avoiding unnecessary complexity, and it enables effective filtering for end users.
#Three-level taxonomy
A three-level taxonomy, Root → Level 1 → Level 2 → Level 3, works well for complex content sets. It provides enough depth and remains manageable.
#Four-level and deeper taxonomy
A four+ level taxonomy (Root → up to Level 6) is valid in industries with established classification standards, such as the Global Industry Classification Standard. Hygraph supports up to 6 nesting levels, without counting the root. Such taxonomies are very powerful, but there could be complexity due to governance. Merges, splits, and reclassifications become heavy operations.
#Implementation tips in Hygraph
Begin with a simple taxonomy, then iterate based on usage data. Avoid over-engineering.
- Assign an owner per taxonomy. Restrict who can create or rename nodes in production, and ensure that significant changes to the taxonomy go through a proper review. By default, editors can create taxonomy nodes. You can use custom roles if you want to limit who can create taxonomy nodes.
- Set up a naming convention for the taxonomy nodes:
- Display name - This is the node name that editors see. Keep it concise, and preferably use sentence case.
- API ID - This is used to query the taxonomy and its nodes. Ensure that it is stable, machine-safe. Avoid renaming this later.
- Keep taxonomy depth less than or equal to three nodes.
- Add, deprecate, and remap nodes versus deleting them. Deleting nodes that are in use is disruptive.
- Allow multiple taxonomy values in models only if required.
- Build out taxonomies in a testing environment. Use the testing environment to manage breaking changes. Use change logs or schema as code to maintain previous versions.
- Keep trees separate for different purposes in larger projects.