Tassonomie

Le tassonomie servono a gestire dizionari controllati di valori. In Discovery possono essere flat o gerarchiche, e vengono create e gestite tramite le apposite pagine ammninistrative in Discovery.

Esempio di tassonomie flat:

• Colori
• Keywords

Esempio di tassonomie gerarchiche:

• categorie (che possono avere sottocategorie)
• Nazioni/Città

A livello di frontend, generalmente le tassonomie vengono utilizzate per filtrare risultati. L'esempio tipico sono i filtri di un sito e-commerce, ma anche le navigazioni tassonomiche che si attivano mostrando i termini tassonomici come hyperlink che l'utente può cliccare. Ad esempio, su una pagina dettaglio prodotto il frontend potrebbe mostrare:

Keywords: casual, comfort fit.

Quando l'utente clicca su una delle keywords parte una navigazione tassonomica che presenta l'elenco dei risultati "casual" o "comfort fit", a seconda di cosa ha cliccato.

Pubblicare le Tassonomie

Perché una tassonomia sia utilizzabile tramite API, è necessario che venga pubblicata. La pubblicazione viene fatta dalla pagina del Taxonomy Manager su Discovery, tramite l'icona "aeroplanino" in corrispondenza della tassonomia che si vuole pubblicare.

Una volta che la tassonomia è stata pubblicata verso la Content API, un client può ottenere il contenuto di una tassonomia con il seguente endpoint REST:

GET /api/v1/taxonomies/<nome tassonomia>

esempio: GET /api/v1/taxonomies/Keywords

Che restituisce una risposta come la seguente:

{
  "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 - Autunno-Inverno"
    },
    {
      "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
    },
    ...
}

Se un termine tassonomico contiene almeno una traduzione, viene aggiunta una property translations, come nel seguente esempio:

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

I termini che non sono stati tradotti non avranno la property translations. Qualora manchino le traduzioni, si consiglia di usare la master_description come fallback.

Fetch delle Tassonomie tramite Connector

Se si utilizza il Connettore Javascript è possibile utilizzare la chiamata:

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

I termini tassonomici recuperati possono poi essere utilizzati per popolare menu dropdown e altri tipi di filtro.

Termini Tassonomici come Filtri di Ricerca

Per cercare tramite termini tassonomici è necessario utilizzare l'ID numerico del termine tassonomico. Utilizzando la chiamata getContents(), ad esempio, occorre inserire un filtro come segue:

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

assumendo che il termine ricercato abbia l'ID 123. L'utilizzo dell'ID garantisce che la ricerca fornisca un match sicuro.

(in roadmap: le versioni future permetteranno la ricerca per master description)

Univocità dei Termini Tassonomici

All'interno della stessa tassonomia, la master_description dei termini tassonomici sono unici, in quanto chiavi di ricerca. Di conseguenza, all'interno di una tassonomia gerarchica non è possibile far apparire lo stesso termine in più punti della gerarchia, ma il termine dev'essere disambiguato con un qualificatore (), ad esempio:

1 Notizie
1.1 Calcio
1.1.1 Ultim'ora (Calcio)
1.2 Basket
1.2.1 Ultim'ora (Basket)

Nell'esempio precedente, si usa il qualificatore per disambiguare "Ultim'ora (Calcio)" rispetto a "Ultim'ora (Basket)", in modo che il termine resti univoco. Qualora non si desideri far apparire il qualificatore sul frontend, è possibile usare le label di traduzione. In tal caso, potremmo rappresentare la tassonomia come segue:

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"

Il frontend dovrà quindi cercare prima la traduzione "it_IT" per l'italiano, e in sua assenza andare in fallback sulla master_description.