---
title: Taxonomy Data Source
slug: experience/taxonomy-data-source
docTags: 
createdAt: 2026-05-12T15:12:17.203Z
---

## 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

```json
{
    "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 Overview](docId\:fuMBUaBWeON_OTO5wfevf)

### 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](docId\:fuMBUaBWeON_OTO5wfevf).

### 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

```json
{
    "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.

## Related Topics

- [Data Sources Overview](docId\:fuMBUaBWeON_OTO5wfevf)
- [Content Data Source](docId\:dfdY32ZAnYtMHKUhzXOrb)
- [Publication Data Source](docId\:dvazUsROOc0TZr-jkvC70)