Taxonomy Data Source

8 min

Overview

The taxonomy data source fetches taxonomy nodes from the Catalog API. It is used to build tag clouds, filter dropdowns, and any component that needs to display or select from the available taxonomy of a publication.

When to use this

Use taxonomy when you need to list or navigate taxonomy nodes . It replaces the deprecated category type and should be used for all new taxonomy-driven components.

Basic Example

{
    "type": "taxonomy",
    "contextKey": "topics",
    "filter": {
        "type": { "value": "topic" }
    }
}

Configuration

Type-specific properties

Property	Type	Default	Description
filter	object	—	Narrows which taxonomy nodes are returned
sort	object or array	—	Controls the ordering of results
includeContents	number \| GetContentsParams	0	Include content items for each taxonomy node. Pass a number to set how many contents to fetch per node, or a full GetContentsParams object for more control
hideEmpty	boolean	—	Exclude taxonomy nodes that have no contents. Only effective when includeContents is set
fetchOptions	object	—	Optional fetch request options (e.g. totalCount: false for faster requests)

For common properties (contextKey, limit, batchSize, etc.) see: Data Sources Overviewd

Filter properties

Filter key	Type	Description
id	StringFilter	Fetch a specific taxonomy node by ID
name	StringFilter	Filter by taxonomy node name
type	StringFilter	Taxonomy type slug (e.g. tag, topic, section)
parentId	StringFilter	Fetch child nodes of a specific parent node
properties	MapFilter	Filter by custom taxonomy properties
contents	ContentListFilter	Filter nodes by whether they contain specific content — { negated?, content?: { operation, value: ContentFilter }, size?: IntFilter }

Supports AND, OR, and condition — see Data Sources Overview.

Sort properties

Sort key	Type	Description
id	{ direction }	Sort by taxonomy node ID
name	{ direction }	Sort by taxonomy node name
property	{ key, valueType, direction }	Sort by a custom property (valueType: STRING or INT)

direction accepts ASC or DESC.

Advanced Features

Hierarchical taxonomy

{
    "type": "taxonomy",
    "contextKey": "subTopics",
    "filter": {
        "parentId": { "value": "$context.taxonomy.id" }
    }
}

Testing Notes / Edge Cases

Type is required in most cases: Omitting type returns all taxonomy node types mixed. Always specify it unless mixing is intentional.

No publication field: TaxonomyFilter has no direct publication field. Use properties or other means to scope if needed.

Large taxonomies: Publications with hundreds of tags can exceed the default batchSize of 24.

hideEmpty requires includeContents: Setting hideEmpty: true without includeContents has no effect — contents must be fetched for the empty check to work. A value of 1 for includeContents is sufficient.

Deprecated category type: Replace with taxonomy and add a type filter matching the equivalent taxonomy type.

Data Sources Overviewdatasou

Content Data Sourcecon

Publication Data Sourcepub