Taxonomies

Classify and organize CXF objects with multiple, hierarchical, localized taxonomies — restricted per template or object type.

Overview

Taxonomies are a flexible way to classify and organize CXF objects. You assign one or more taxonomies to an object — a Contact, a Document, a Content Instance, and more — to categorize it. Taxonomies can be hierarchical (parent-child), localized into multiple languages, and restricted so that each object can only use an approved set. For the mental model of how classification fits the shared object model, see Core concepts.

The model has three parts:

1. Define a taxonomy (a term like Technology or VIP customer).
2. Restrict which taxonomies an object can use — per Template, or per object type.
3. Assign taxonomies to objects.

Where to find it

You can manage Taxonomies in two places:

• Utilities in each module — a direct shortcut to that object type’s taxonomy instances.
• Content → Content Templates → Taxonomies — the fuller view, where you manage the taxonomy template and its instances together.

There is exactly one taxonomy template per object type — a system constraint.

Properties

A taxonomy has the following properties:

Property	Type	Required	Description
title	string	Yes	Display name of the taxonomy.
slug	string	Yes	Unique identifier.
taxonomy_object_type	enum	Yes	The object type this taxonomy classifies (for example contacts, documents, content_instances).
parent_id	reference	No	Parent taxonomy, for hierarchies.
sequence	number	No	Order among sibling taxonomies, for hierarchies.
description	string	No	Optional description.
versions	array	No	Localized versions — each with its own title and slug per language. See Localization.
created_at	datetime	Auto	When the taxonomy was created.
updated_at	datetime	Auto	When the taxonomy was last updated.
deleted_at	datetime	Auto	When the taxonomy was archived (Archive); empty unless archived.

Like any object, a taxonomy can also be extended with custom Attributes on top of these properties.

Restricting taxonomies

Which taxonomies an object can use depends on whether its object type uses Templates:

• Template-based objects (Content Instances, Documents, Orders) — the Template declares the allowed taxonomies:
  • taxonomies_ids — the taxonomies instances of this template may use.
  • default_taxonomies_ids — taxonomies applied to new instances by default.
• Non-template objects (Contacts, Organizations, Users) — an object can use any taxonomy whose taxonomy_object_type matches its own type.

Assigning a taxonomy that isn’t allowed is rejected with a validation error.

Hierarchies

Hierarchies are built from two properties: parent_id sets a taxonomy’s parent, and sequence sets its order among its siblings. Together they form a parent-child tree (for example Products → Electronics → Smartphones).

Descendants are allowed automatically. When a parent taxonomy is allowed for a Template, all of its descendants are allowed too — you don’t have to list each child.

Localization

A taxonomy can carry versions for different languages. Each version has its own title and slug (plus language, environment, and status). When an object’s taxonomies are read in a given language, the matching version’s title and slug are used — for example, Technology (en) / Tecnología (es).

Behaviour & rules

• Multiple per object. An object can hold many taxonomies at once.
• Validated on assignment. Only allowed taxonomies (see Restricting taxonomies) can be assigned; others are rejected.
• Assign by id or slug. You can reference a taxonomy by either.
• Immutable while in use. Once a taxonomy is assigned to any object, its slug, parent_id, and Template can’t be changed — title and description still can. To change a locked field, create a new taxonomy instead.

Seeds

Taxonomies travel between environments with Seeds, and support both seed types. A taxonomy is seeded as a content_instances record with type: "taxonomies".

Seed type	Supported	Hierarchies	Reference helpers
Structural	Yes	Yes (parent_id)	Yes
Instance	Yes	No	No

Hierarchies (parent_id) only apply in structural seeds. To load taxonomies in bulk with an instance seed, insert them flat and then set their parent-child relationships from the UI.

Structural seed

Each taxonomy is an item with object_type: "content_instances". Hierarchies use parent_id, and template_id is resolved with a reference helper:

[
  {
    "object_type": "content_instances",
    "data": {
      "title": "Technology",
      "slug": "technology",
      "type": "taxonomies",
      "taxonomy_object_type": "content_instances",
      "template_id": "{{getRecordAttribute('content_templates', 'slug', 'default-content-instances')}}",
      "versions": [
        { "title": "Technology", "slug": "technology", "language": "en", "environment": "production", "status": "published" }
      ]
    }
  },
  {
    "object_type": "content_instances",
    "data": {
      "title": "Promotions",
      "slug": "promotions",
      "type": "taxonomies",
      "taxonomy_object_type": "content_instances",
      "template_id": "{{getRecordAttribute('content_templates', 'slug', 'default-content-instances')}}",
      "parent_id": "{{getContentInstance('default-content-instances', 'slug', 'technology')}}",
      "parent_object_type": "content_instances",
      "versions": [
        { "title": "Promotions", "slug": "promotions", "language": "en", "environment": "production", "status": "published" }
      ]
    }
  }
]

Instance seed

Instance seeds bulk-insert taxonomies as flat records — no object_type wrapper, no reference helpers, and no hierarchy:

[
  {
    "slug": "technology",
    "title": "Technology",
    "type": "taxonomies",
    "taxonomy_object_type": "content_instances",
    "versions": [
      { "title": "Technology", "slug": "technology", "language": "en", "environment": "production", "status": "published" }
    ]
  },
  {
    "slug": "news",
    "title": "News",
    "type": "taxonomies",
    "taxonomy_object_type": "content_instances",
    "versions": [
      { "title": "News", "slug": "news", "language": "en", "environment": "production", "status": "published" }
    ]
  }
]

Governance & permissions

Only a super admin or Master can create, edit, and delete taxonomies.

API access

Assign taxonomies by setting an object’s taxonomies to a list of taxonomy ids or slugs through the API reference. Taxonomies themselves are managed as content instances of type taxonomies.

Related

Tags

Another way to label and group objects.

Object types

Which object types support Taxonomies.