Taxonomies

Taxonomies are used to manage controlled dictionaries of values. In Discovery they can be flat or hierarchical, and are created and managed through the appropriate administrative pages in Discovery.

Example of flat taxonomies:

• Colors
• Keywords

Example of hierarchical taxonomies:

• categories (which may have subcategories)
• Nations/Cities

At the frontend level, taxonomies are generally used to filter results. The typical example is the filters of an e-commerce site, but also the taxonomic navigations which are activated by showing the taxonomic terms as hyperlinks that the user can click. For example, on a product detail page the frontend might show:

Keywords: casual, comfort fit.

When the user clicks on one of the keywords, a taxonomic navigation starts which presents a list of "casual" or "comfort fit" results, depending on what he clicked on.

Publish Taxonomies

For a taxonomy to be usable via API, it must be published. The publication is made from the Taxonomy Manager page on Discovery, using the "airplane" icon corresponding to the taxonomy you want to publish.

Once the taxonomy has been published to the Content API, a client can obtain the contents of a taxonomy with the following REST endpoint:

GET /api/v1/taxonomies/<taxonomy name>

example: GET /api/v1/taxonomies/Keywords

Which returns a response like the following:

{
    "name": "Keywords",
    "count": 35,
    "items": [
        {
        "id": 374,
        "master_description": "aaaa"
        },
        {
        "id": 375,
        "master_description": "aaaaa"
        },
    ...
    ]
}

{
    "name": "eCommerce",
    "count": 15,
    "items": [
        {
        "id": 332,
        "master_description": "2023 - Primavera-Estate"
        },
        {
        "id": 333,
        "master_description": "2023 - Autumn-Winter"
        },
        {
        "id": 334,
        "master_description": "2024 - Primavera-Estate"
        },
        {
        "id": 335,
        "master_description": "2024 - Primavera-Estate"
        },
        {
        "id": 339,
        "master_description": "Kids"
        "parent_id": 334
        },
        {
        "id": 336,
        "master_description": "Kids Category"
        "parent_id": 335
        },
        ...
    ]
}

If a taxonomic term contains at least one translation, a translations property is added, as in the following example:

"items": [
{
    "id": 332,
    "master_description": "Hello",
    "translations": {
        "it_IT": "Ciao",
        "es_ES": "Hello"
    }
},

Terms that have not been translated will not have the translations property. If translations are missing, it is recommended to use master_description as a fallback.

Fetch Taxonomies via Connector

If you use the Javascript Connector you can use the call:

const terms = getTaxonomy('Keywords');
// oppure, React Hook:
const terms = useDiscoveryTaxonomy('Keywords');

The retrieved taxonomic terms can then be used to populate dropdown menus and other types of filters.

Taxonomic Terms as Search Filters

To search by taxonomic terms you must use the numeric ID of the taxonomic term. Using the getContents() call, for example, you would insert a filter as follows:

const results = useDiscoveryContents({
    type: "...",
    filter: {
        keyword: 123
    }
})

assuming the search term has the ID 123. Using the ID ensures that the search provides a safe match.

(in roadmap: future versions will allow searching by master description)

Uniqueness of Taxonomic Terms

Within the same taxonomy, the master_description of the taxonomic terms are unique, as search keys. Consequently, within a hierarchical taxonomy it is not possible to have the same term appear in multiple places in the hierarchy, but the term must be disambiguated with a () qualifier, for example:

1 News
1.1 Football
1.1.1 Last minute (Football)
1.2 Basket
1.2.1 Last minute (Basketball)

In the example above, we use the qualifier to disambiguate "Breaking Hours (Football)" from "Breaking Hours (Basketball)" so that the term remains unique. If you don't want the qualifier to appear on the frontend, you can use translation labels. In that case, we could represent the taxonomy as follows:

1 master_description = "Notizie"
1.1 master_description = "Calcio"
1.1.1 master_description = "Ultim'ora (Calcio)", translations[it_IT] = "Ultim'ora"
1.2 master_description = "Basket"
1.2.1 master_description = "Ultim'ora (Basket)"`, `translations[it_IT] = "Ultim'ora"

The frontend will therefore have to first look for the "it_IT" translation for Italian, and in its absence fallback to the master_description.