Go Behind the Experience to see how Tecovas brings the West to life with Sanity 🤠 July 18th
Published August 02, 2023

Topic Taxonomy Setup & Use

By Andy Fitzgerald

Topic taxonomies give you a way to group ideas or things that have meaningful associations for your users or your business, but are not necessarily sub-types of one another or of a common parent concept. "Prescription cat food" is "cat food," which is in turn "pet food." Your users however, may look for "kidney diet" cat food under the "cat" category—and "cat food" is not a cat. This is where topic taxonomies can help.

In this guide you'll learn what makes "topic" taxonomies different from other kinds of taxonomy structures, like type or faceted taxonomies, and you'll learn how to set up a topic taxonomy in the Sanity Taxonomy Manager plugin. You'll also see examples of how to integrate your taxonomy into document schemes and query across related concepts for tagged documents.

An archive detail page from the Smithsonian, featuring relevant (but not necessarily hierarchical) topic tags

Topic classification is often used to provide multiple pathways to a concept, article, or product. In the example from the Smithsonian Institute above, any of a dozen or so Topics eventually lead one to the Smithsonian's archival record on Francis Gary Powers.

Topic classification is also a powerful way to express brand differentiation. Columbia and Patagonia both make and sell a similar range of outdoor activity apparel for adults and kids, and products for both companies fall into clearly delineated types: jackets, shirts, base layers, pants, etc. Topical grouping on each site (which, when at the top level we usually call "categories") tell users of each site what kind of "place" it is.

Detail views of the topical categories on the Columbia and Patagonia retail websites.

Key Features

  • Relationships: Topic taxonomies may only be a singe level, or comparatively shallow, and often combine parent-child "is-a" and whole-part "has-a" relationships freely.
  • Adaptability: Topic taxonomies are much more flexible than "type" taxonomies, and can be used to express a brand's (or user's) particular perspective.
  • Size Limitations: Topic taxonomies are often are not very large: because the relationships are less strict than in many Type taxonomies, large structures in Topic taxonomies may end up hiding concepts in categories users may not expect.

When to Use a Formal Taxonomy for Topics

Not all Topic and Category vocabularies need to be managed as a formal, standards-based taxonomy. If you're Mud Bay, a health-focused pet food and supplies store with products mostly for dogs and cats, a category list of "dog," "cat," and "small animal" (everything else) stored in your CMS may work just fine. If you're Chewey.com, however, and you carry retail and pharmacy supplies for dogs, cats, fish, birds, reptiles, farm animals, and more, you'll likely see usability, governance, and scale efficiencies by managing your topic taxonomy more formally.

You may also consider formally modeling and managing your topics if you're sharing them between systems, such as a CMS, a PIM, and/or a CRM. Formal modeling may also be beneficial if you're combining your topics with other formal structures (such as type or faceted taxonomies) to generate recommendations and insight from user behavior, or to provide AI tools the ground truth they need to return reliable, trustworthy results.

Setting Up a Topic Taxonomy

1. Install Sanity Taxonomy Manager


These instructions assume you have already identified a taxonomy to adopt or adapt, or have designed one for your specific content needs. Taxonomy provisioning and creation is beyond the scope of this guide, but you can find a primer on finding and designing taxonomies in the Sanity Taxonomy Manager docs.

The Taxonomy Manager plugin allows you to create standards compliant relationships that help keep your taxonomy interoperable and reusable.

2. Create a new concept scheme

Concept Schemes are used to create multiple taxonomies in a single project, and, where needed use the same concepts across them. This gives you a single source of truth for each concept you define, and allows you to establish semantic relationships between individual taxonomies.

Add a new Concept Scheme with either the global "new document" button, or the "new document" button in the Concept Schemes list view

3. Name and describe your taxonomy

Add a clear name and describe the purpose and goals of your taxonomy to users. Tagging content with managed terms may be new to your content creators: good descriptions can help users understand why the tagging step is important.


Describe what your taxonomy is for, as opposed to only what it is of: a taxonomy of a topic may feel superfluous; a taxonomy for a purpose can help bring authors and collaborators along.

4. Add topic concepts

For small or non-hierarchical lists of topics, you may elect not to use Top Concepts at the highest level of the hierarchy. This can be a good option when you have a flat list, or some concepts without child concepts, or when you're going to want users to be able to select any term for tagging (including those at the highest level).


Define your concepts as you go. This will help the people using your taxonomy apply it as intended.

Where extra information about how a term is used in the context of your taxonomy is needed, consider adding a "Scope Note" to explain coverage, specialized usage, and/or rules for assigning a topic.

5. Add child concepts (optional)

Child concepts may be narrower types, or individual parts of a larger whole.


Topic taxonomies may not need narrower concepts; don't add them just because you can: make sure the added complexity has a purpose.

6. Add the taxonomy to a Sanity document scheme

You're now ready to publish your taxonomy, integrate it into your content scheme, and start tagging content. Taxonomy Manager includes two helper functions for ensuring that only the appropriate concepts are available for a given field:

Querying Content

Once your content is tagged, the semantics built into your topic taxonomy allow you to retrieve all topics related to a resource, retrieve all resources tagged with a given topic (or topics), or create a list or resources by topic and/or subtopic (for example, to help in the creation of topic-based navigation).

Get content tagged with a concept by prefLabel

*[_type == "post" && "Snowshoeing" in topic[]->prefLabel]


Querying by prefLabel is convenient in some situations, but if your labels ever change, you'll need to rewrite all your queries. You can write more resilient code by querying by conceptID.

Get content tagged with a concept by conceptID

[_type == "post" && "a675a1" in topic[]->conceptId]

Each concept you create in Taxonomy Manager is automatically given a unique conceptId. You can find the conceptId below the Base URI field in the concept editor pane:

Each concept has a unique ID you can use to query and reference concepts


Taxonomy Manager's conceptId allows you to reuse and reference the same Concepts and Concept Schemes across studios and datasets.

Generate a topic list for a given post

*[_type == "post" && title == "Best Base Layers for Snow Sports"]{
  "topics": topic[]->prefLabel

Generate a list of articles for each topic

*[_type == "skosConceptScheme" && schemeId == "04ab34"].concepts[]->{
  "topic": prefLabel,
  "articles": *[_type == "post" && references(^._id)].title

Well defined, standards compliant taxonomy provides a ground truth foundation for scores of different discovery, personalization, and business intelligence applications. The queries above offer just a few examples of how assiduously applied taxonomy can help you manage content based on the relationships you've created. Your dataset, taxonomy, and goals will be the most natural drivers for how your taxonomies are used to create value.

Learn More

Find more examples, applications, and tips in the Sanity Taxonomy Manager Docs >>

Sanity – build remarkable experiences at scale

Sanity Composable Content Cloud is the headless CMS that gives you (and your team) a content backend to drive websites and applications with modern tooling. It offers a real-time editing environment for content creators that’s easy to configure but designed to be customized with JavaScript and React when needed. With the hosted document store, you query content freely and easily integrate with any framework or data source to distribute and enrich content.

Sanity scales from weekend projects to enterprise needs and is used by companies like Puma, AT&T, Burger King, Tata, and Figma.

Other guides by author

Search Taxonomy Setup & Use

Search taxonomies (or thesauri) are crucial tools in ensuring that your site search feature gets users where they want to go.

Andy Fitzgerald
Go to Search Taxonomy Setup & Use

Faceted Taxonomy Setup & Use

Faceted taxonomies are a great option for organizing resources that don't fit neatly into hierarchical structures.

Andy Fitzgerald
Go to Faceted Taxonomy Setup & Use

Type Taxonomy Setup & Use

Add semantic relationships to your content to make it more discoverable and reusable across contexts.

Andy Fitzgerald
Go to Type Taxonomy Setup & Use

Self-Hosting Sanity Studio with GitHub Actions

A comprehensive guide to self-hosting Sanity Studio on DreamHost with GitHub Actions for continuous integration.

This is an external link at:www.andyfitzgeraldconsulting.com
Andy Fitzgerald
Go to Self-Hosting Sanity Studio with GitHub Actions