A taxonomy is a hierarchical grouping of related concepts. In Oracle Content and Experience, taxonomies help content authors and client applications classify content into well-defined categories.

Let’s have a closer look by taking a vehicles taxonomy as an example.

Description of headless_taxonomies-example.png follows
Description of the illustration headless_taxonomies-example.png

In this example, the Vehicles taxonomy has two top categories (Cars and Trucks), and these categories in turn have several children. Of course, those child categories can each have their own child categories, and so on. Such a structure of logical entities essentially represents a hierarchical set of categories.

The following topics describe Oracle Content and Experience taxonomies:

Taxonomies from a Management Perspective

Once a taxonomy and categories are defined, content authors can classify content into categories of that taxonomy.

For example, an asset called Ford Fiesta would be classified under /Vehicles/Cars/Sedan. Any number of assets of any kind can be classified into a category. A category is merely a logical placeholder for content that belongs to a specific concept.

Adding assets to a category is simple: select the assets to be added to a category and choose the category to add them to.

Description of headless_taxonomies-categories.png follows
Description of the illustration headless_taxonomies-categories.png

Once assets are added to categories, the Oracle Content and Experience web interface shows them in an intuitive tree-like navigation structure. Content authors can select a specific category to view or manage its content. This lets you use taxonomies as an organization tool for content management.

Description of headless_taxonomies-organization.png follows
Description of the illustration headless_taxonomies-organization.png

An Oracle Content and Experience instance can have as many taxonomies as needed. A single repository can have multiple taxonomies, and the same taxonomy can be enabled in multiple repositories. In addition, assets in a management context can belong to multiple taxonomies. This many-to-many relationship between taxonomies, repositories, and assets helps content architects design and use sophisticated content-classification models.

Description of headless_taxonomies-relationships.png follows
Description of the illustration headless_taxonomies-relationships.png

Taxonomies themselves might change over time. When a taxonomy changes, the categorization of the assets also changes as a result (automatic recategorization). Suppose a category is moved from one parent category to another. In that case, assets that belong to the category that moved (children of the category) continue to belong to the same parent, but would acquire a new grandparent. If a category is deleted, however, the assets belonging to that category are promoted to the parent category, as you would expect.

In this sense, categories are not containers of assets. Instead, the right way to think about categorization is in terms of relationships. Assets, by virtue of categorization, are associated with a category.

Taxonomy Life Cycle

Changes to a taxonomy itself can have far-reaching consequences for the nature of categorization. Such taxonomy changes are likely to be a multistep process involving a number of people and potentially multiple groups or teams.

That’s why Oracle Content and Experience uses an orchestrated life cycle for taxonomy changes:

  • Taxonomies are always created in a draft state. They are initially considered to be in the process of structural definition and don’t allow assets to be added to their categories.
  • Once the taxonomy authors are satisfied with the structure of a taxonomy, they graduate it to a promoted state. This is the state at which the taxonomy can be enabled for a repository, which allows content authors to start classifying content into it. However, no changes to the taxonomy structure itself are allowed in this state.
  • If the structure of a taxonomy needs to change after assets have been classified into it, that taxonomy needs to be versioned and turned back into draft mode. However, users can continue to categorize content into the promoted version of the taxonomy. The draft taxonomy can subsequently be promoted, which results in automatic recategorization of assets into the new structure of the taxonomy (using the general rules described in the preceding text).
  • A taxonomy itself can be published to channels like any other asset. Once published, taxonomy and categorization information is available in the delivery API. This helps clients present content based on taxonomy (such as product listings, faceted navigation, and some types of menus).

Description of headless_taxonomies-lifecycles.png follows
Description of the illustration headless_taxonomies-lifecycles.png

Taxonomies from a Delivery Perspective

Taxonomies are published, just like assets. Once a taxonomy is published, it’s available in the delivery API.

There are two places where taxonomy information surfaces in the delivery API:

  1. Discovering the Structure of a Taxonomy
  2. Discovering Asset Categorization

Discovering the Structure of a Taxonomy

There are many APIs that help navigate the structure of a taxonomy or category by category listing.

One simple way to get all category information of a taxonomy is using an API in this form:

GET http://.../content/published/api/v1.1/taxonomies/52446BF67CE74F229AF9F178448BCB80/

Discovering Asset Categorization

The standard asset-listing resource can also list assets classified to a specific category (or categories).

This is done with this simple form of the API:

GET http://.../published/api/v1.1/items?q=( eq 

This produces a response like the following one:

  "items": [
      "name": "Ford Fiesta",
      "description": "",
      "links": [],
      "id": "CORE23B05BB961AE4EE3AE4ED9962A0440ED",
      "type": "Vehicles"
      "name": "Ford Fiesta 2019 Launch",
      "description": "",
      "links": [],
      "id": "COREC6C72D74EAA0477AAE966CF154CB16C7",
      "type": "Marketing-Blog"
  "links": []

To make this type of request, you would have to know the ID of the category. However, there is another way to discover assets of a category by using a friendly ID (slug or API name). Each category can have a unique handle, which is a string that’s both human-readable and addressable as an ID. The API name of a category can simply be added to a category at the time of creation or any time thereafter. The API name itself can be used instead of the category ID. Also note that the API name of a category, like its ID, must be unique across taxonomies.

Suppose we have all-cars as the API name for the Cars category and all-cars.sedans for the Cars/Sedan category. Then the preceding API call can also be written as follows:

GET http://.../content/published/api/v1.1/items?q=(taxonomies.categories.apiName eq 

This lets client applications surface meaningful URLs instead of passing around IDs.