Designing a Taxonomy That Scales

A taxonomy is the set of labels you use to group and find content: categories, tags, topics, audiences, regions, product lines. Get it right and editors file content in seconds, your site can filter and build landing pages from it, and new channels can reuse it. Get it wrong and you end up with three spellings of every tag and filters that miss half the content.

In Agility you build a taxonomy from the same parts as the rest of your content model: Drop-down List fields, content lists, and Linked Content fields. This page shows how to choose between them and how to keep the result healthy as it grows.

Choose the right tool for each dimension

Treat each way of grouping content (topic, audience, region, format) as its own dimension, and pick a tool per dimension.

Tool	How it works	Who changes the terms	Best for
Drop-down List field	Fixed choices defined in the model; the API returns the selected choice's value	Developers or admins, by editing the model	Small, stable sets your code depends on: content type, layout variant, priority
Linked Content to a terms list, single (Dropdown List render type)	Each term is an item in a content list; the item stores one term's content ID	Editors, by adding items to the list	One category per item
Linked Content to a terms list, many (Search List Box render type)	As above, storing a comma-separated list of term IDs	Editors	Tags and topics, several per item
Structure (separate lists, sitemaps)	Where the content lives is the classification	Developers or admins	A dimension where every item belongs to exactly one value, such as a destination site

Rules of thumb:

• Use a Drop-down List when adding a term should involve a developer anyway, because the code has to handle it. The stored values are stable strings your code can switch on, and editors see the labels.
• Use a terms list when editors should be able to add terms without a code change, when terms need their own fields (a description, a slug, an image), or when a term has its own page.
• Use structure when an item can only ever have one value. A selector that always holds the same answer is one more thing to get wrong. See Publishing to Multiple Destinations for the trade-offs when the dimension is "which channel".

Model a terms list

The basic setup is described in Tagging Content in Agility: a content model for the term, a content list built from it, and a Linked Content field on the content you want to classify. For a taxonomy that will grow, give the term model a few more fields than a title:

Field	Type	Why
Title	Text	The label editors and visitors see
Slug	Text	A stable, URL-safe key for term pages and filters in URLs
Description	Multi-Line Text	What belongs under this term, so editors file content consistently. It also helps search engines and AI agents
Active	True/False (optional)	Retire a term without deleting it

Then add the Linked Content field to each model that uses the taxonomy:

• Link to: Content
• Link Type: Specific Item(s) from a List
• Render UI: Search List Box for tags (Dropdown List for a single category)
• Content Reference: your terms list
• Save Value to Field / Save Text to Field: new hidden fields, for example Tags_ValueField and Tags_TextField

Use one terms list per dimension (Topics, Audiences, Regions) rather than one big Tags list with prefixes like audience- and region-. Separate lists keep each picker short and let you give each dimension its own fields and rules.

Hierarchy

Most taxonomies only need one level. If you need two (for example Category > Subcategory), model each level as its own list, and give the lower level a Dropdown List link to its parent. Content then links to the most specific level, and your front end walks up to the parent. Avoid deeper trees unless you have a real navigation need: every extra level is more for editors to maintain and more for code to resolve.

Querying by taxonomy

The companion value field is the cheapest way to filter, because it stores plain content IDs and needs no expansion.

For a single category:

fields.category_ValueField[eq]"110"

For tags (a comma-separated list of IDs), use contains:

fields.tags_ValueField[contains]"32"

Test contains against your own data before you build on it, so you know exactly which items match. Operator details are in GraphQL & Rest API Filtering.

Other things to know:

• Render names from the linked items, not from the text field. The text companion field is written when an item is saved. Read the term's title from the linked item (or fetch the terms list once and look terms up by ID), so a renamed term shows its new name everywhere.
• Fetch terms lists in full. Pass take on every list request: the Content Fetch API returns 10 items by default and GraphQL lists return 50. The maximum per request is 250.
• Term IDs work across locales. When you copy a term into another locale, the copy keeps the same contentID, so the IDs stored on your content still match. Translate the term's title per locale, and consider marking the Slug field Constant across all languages if your URLs use the same slug in every locale. See Choosing a Localization Strategy.

Governance: keeping it clean

Taxonomies decay through small, reasonable-looking additions. Decide these before launch:

1. One owner per dimension. Someone decides whether a new term is needed, merges duplicates and retires unused terms.
2. Naming rules. Singular or plural, capitalization, no abbreviations. Write them in the term model's field descriptions so editors see them.
3. A definition for every term. If two terms can't be told apart by their descriptions, merge them.
4. A limit per item. For example "at most five tags". Make it an editorial rule and check it in review.
5. Retire before you delete. Mark a term inactive first. Before deleting a term, filter on the value field to find items that use it, and re-tag them. Stored IDs aren't removed from other items for you.
6. A review rhythm. Once a quarter, list terms with few or no items and decide whether to merge or retire them.

Common mistakes

• Tags typed as free text. Every variation becomes a new tag. Link to a terms list instead.
• One Tags list doing four jobs. Split it by dimension.
• A Checkbox List on a terms list that grows. It becomes unusable past a short list. Use a Search List Box.
• Using rich text to list related topics. The API can't filter on text inside an HTML field.
• Category pages built from hand-picked lists. If a page should show "everything in this topic", query by the term, so new content appears without editing the page.

Related

• Tagging Content in Agility
• Nest, Link or Share? Choosing Linked Content Field Types
• Content Modeling Anti-Patterns
• GraphQL & Rest API Filtering
• Publishing to Multiple Destinations