Taxonomies in Optimizely Graph

8 min

Taxonomy in Optimizely Content Management System (CMS) (SaaS) provides a structured system for organizing content. A taxonomy consists of terms that classify and categorize content. CMS (SaaS) supports hierarchical terms called Categories. Categories support parent-child relationships with multiple nesting levels, which enables taxonomic organization, browsable navigation paths, and logical grouping of related content.

Taxonomies are indexed in Optimizely Graph in two locations: as term references on content items (_itemMetadata.categories) and as standalone taxonomy term documents (the _TaxonomyTerm type). This supports taxonomy-based filtering and navigation in headless content delivery scenarios.

Content items store category assignments as URI references (cms://taxonomy/categories/electronics), and taxonomy terms are indexed as separate documents that contain localized metadata.

Categories on content

The _itemMetadata contract includes a categories field that contains an array of taxonomy term reference URIs:

query GetContentWithTaxonomy {
  _Content {
    items {
      _itemMetadata {
        key
        displayName
        categories
      }
    }
  }
}

Each reference is a URI string in the format SCHEME://AUTHORITY/TAXONOMY_KEY/TERM_KEY. Only CMS internal taxonomies are supported, which use the cms://taxonomy/categories/* format:

cms://taxonomy/categories/electronics

cms://taxonomy/categories/laptops

These references link content items to taxonomy terms. The term metadata (display name, description, and usage) is stored in separate _TaxonomyTerm documents. The categories field contains only these key URIs; it does not include display names. To retrieve localized display names or descriptions, query the _TaxonomyTerm documents by key.

Note Only categories with the Visible flag set to true are indexed on content. Categories that are not visible are excluded from Graph indexing.

_TaxonomyTerm type

_TaxonomyTerm is a standalone type in the Graph schema. Each category is indexed as its own _TaxonomyTerm document that you query directly. Content items reference terms by key through _itemMetadata.categories; the term details, including localized display names, are on _TaxonomyTerm, not on _itemMetadata. The _TaxonomyTerm type defines the following fields:

Field	Type	Description
key	String	The category's unique identifier used in APIs and code.
displayName	String	The localized display name shown in the UI.
description	String	An optional localized description that explains the category's purpose.
usage	String	Metadata that indicates the intended scope: Public for general use, Internal for internal classification. Both types are indexed and queryable.
taxonomy	String	The taxonomy identifier, typically categories for category terms.

Language fallback

_TaxonomyTerm display names and descriptions are localized. When you query a term, displayName and description return the value for the language context of the query. The key, usage, and taxonomy fields are language-independent and stay constant across all languages.

Optimizely Graph does not fall back to the master language for other languages:

Master (default) language – If a term has no translation, displayName and description return the value stored when the category was created.

Other languages – If a term has no translation in the queried language, displayName and description return a dash placeholder (–), not the master-language value.

This behavior is shared by Admin mode, the API, and Optimizely Graph. Because Graph does not fall back across languages, implement your own fallback if you need a non-empty label in every language. For example, query the master language for any term that returns –, or treat – as a missing translation in your application.

Query taxonomy terms

Taxonomy terms are indexed as separate _TaxonomyTerm documents. Query these documents directly to retrieve term metadata or filter by usage:

query PublicTermsQuery {
  _TaxonomyTerm(
    where: {
      _metadata: {
        usage: { eq: "Public" }
      }
    }
  ) {
    items {
      _metadata {
        key
        displayName
        usage
      }
    }
  }
}

Note The usage field on _TaxonomyTerm documents is metadata that indicates intended scope. It does not restrict which categories are indexed on content or limit access. Developers choose whether to filter by usage based on application requirements.

Query content by category

Filter content by category using the URI reference format in the _itemMetadata.categories field:

query SingleCategoryQuery {
  _Content(
    where: {
      _itemMetadata: {
        categories: {
          eq: "cms://taxonomy/categories/electronics"
        }
      }
    }
  ) {
    items {
      _metadata {
        key
        displayName
      }
      _itemMetadata {
        categories
      }
    }
  }
}

Multiple categories

Use the in operator to find content tagged with any of several categories:

query MultipleCategoriesQuery {
  _Content(
    where: {
      _itemMetadata: {
        categories: {
          in: [
            "cms://taxonomy/categories/electronics",
            "cms://taxonomy/categories/laptops",
            "cms://taxonomy/categories/mobile"
          ]
        }
      }
    }
  ) {
    items {
      _metadata {
        key
        displayName
      }
      _itemMetadata {
        categories
      }
    }
  }
}

Combine with content type

Combine category filtering with content type filtering using the _and operator:

query CategoryAndTypeQuery {
  _Content(
    where: {
      _and: [
        {
          _metadata: {
            types: { eq: "ProductPage" }
          }
        }
        {
          _itemMetadata: {
            categories: {
              eq: "cms://taxonomy/categories/electronics"
            }
          }
        }
      ]
    }
  ) {
    items {
      _metadata {
        key
        displayName
      }
      _itemMetadata {
        categories
      }
    }
  }
}