Taxonomies and Tags

Last Updated: Apr 24, 2024
documentation for the dotCMS Content Management System

One of the most important decisions you will make about your dotCMS installation is how to label and organize your content. Taxonomies enable you to organize content according to different keywords and relationships, making it easier for site users to find content they're interested in, and enabling you to more easily create dynamic content pulls to display information appropriate to your pages and users.


Taxonomies work best when they are planned ahead of time; just as you put tabs on the top of folders when you place them into a filing cabinet, content needs to be labeled and segregated as it is entered into the dotCMS content repository so that dynamic pages naturally pull and display content logically.

In addition, improper use of taxonomies can make content creation redundant or confusing, and can make it difficult to dynamically extract content for front-end users. Therefore it is strongly recommended that you pre-plan your use of dotCMS taxonomies before building out your site, to leverage the power of the taxonomies and simplify content creation and site maintenance. It is very difficult to go back later and label content after it has already been entered into the system.

For a comparison of taxonomies and more information on the advantages and disadvantages of each, please see Combining and Comparing Taxonomies, below.

Taxonomy Features

dotCMS has three basic data segregation strategies that you can take advantage of as you set up content types and plan content creation: Tags, Categories, and Relationships.


Tags are keywords associated with a piece of Content. Content of a Content Type that contains a Tag field may be associated with any number of Tags, and you can create queries to search for Content by Tags.

When users need to find content by keyword search but you do not know ahead of time what keywords will be associated with Content, Tags are usually the best choice. News items, press releases, etc., are content types that typically have Tag fields because of the limitless number of topics they can cover; Tags enable users to more easily find content which matches almost any subject, even one that is added at some time in the future.

Several features of Tags make them a valuable tool for user-generated content:


Despite their usefulness, Tags have several important limitations:

  • Tags cannot be reliably used to pull dynamic content lists.
    • Content creators can tag content with any keyword(s), so you can not control what keywords will be added.
    • If you wish to create queries or Widgets to dynamically pull content based on pre-defined terms or keywords, use Categories or Relationships instead.
  • Tags can not enforce the use of specific terms or spelling.
    • Content creators can use different terms for the same thing, and can spell the same term in different ways.
    • However when the content creator types into the Tag field, dotCMS will display suggested tags from the Tags which have already been used to encourage the re-use of tags.

Pre-Populating Tag Fields

You can pre-populate your tag pool for content creators, so that when they type into the Tags field, your pre-defined list of tags is displayed (helping to prevent mis-spellings or use of different terms for the same topic).

To pre-populate your Tags:

  1. Create a comma separated tag list.
  2. Add a new piece of dummy content to the system (of any Content Type that contains a Tag field).
  3. Paste the complete tag list (from step #1, above) into the Tag field for that piece of content.
  4. Save the dummy content.
  5. Delete the dummy content.

This will add all of those tags to your tag pool. When content creators type at least three letters into the Tag field of any Content, all of your tags that contain their typed letters will be suggested to them, so they may select your pre-defined tags instead of creating a new tag of their own.


Categories are drop down lists of predefined labels. Webmasters often prefer to present users with predefined drop down lists of labels because they can be used reliably on dynamic pages to pull content whereas tags are difficult to predict.


However due to their simplicity, categories are often over-used as a taxonomy. Categories have the following important limitations:

  • Categories should not duplicate content.
    • Use Categories for logical labels only.
  • Top-level Category lists should also remain relatively short in length.
    • If you have more than 30 top-level labels in the initial planning stages, your category list will probably grow too large and unwieldy as your site scales.
  • Category hierarchies should not include more than 3 levels.
    • A maximum of 2 levels is recommended.

As a general rule, do NOT use a Category Field if:

  • You have more than 30 top-level Category labels in the initial planning stages.
    • Consider using Tags instead.
  • Category names will also match content titles.


Relationships define a pre-defined hierarchical relationship among different Content Types. Individual pieces of Content may then be related to other content in a parent-child relationship.

When certain types of content need to be found by related content in a hierarchy (e.g. you need to find children of an item, or the parent or siblings of an item), then Relationships are usually the best solution.

Note that when you create Relationships, webmasters define what relationships may be created among different Content Types. But content creators - not webmasters - maintain the related content among the individual Content items.


Consider a site for an organization that manages 50 little league sports Associations. Each association has 40 Teams, with 35 Players per team. Relationships can help build powerful dynamic pages to display this information, without redundant labels or processes.

  • Since there are probably multiple pieces of information about each association, team, and player (such as name, location, coach, etc.), each of these types should be structured content rather than a Category.
  • First, create a Relationship between the Association and Team content types.
  • Next, create a second Relationship between the Team and Player content types.

These two relationships allow you to build dynamic pages to search for content based on the 3-level relationship chain you have created:

  • You can find which team (or even multiple teams) a player belongs to by searching for the parent(s) of the player object.
  • You can find all players on a team by searching for all children of the team object.
  • You can find the association a player belongs to by searching for the parent team of the player, and then the parent association of the team.
  • You can find all teams in an association by searching for all the children of the association.
  • You can find all players in the association by searching for all teams within that association, and all players on each team.

There is no limit to the number of Associations, Teams, or Players that can be entered into the system. Your content can grow and expand without changing dynamic pages and without needing to add new categories when new associations or teams are added.

Additional Taxonomy Options

In addition to the three features above, which are specifically designed for taxonomies, you can also use some other, more general dotCMS features to implement taxonomies — including Folders, Standard Content Type fields, and Custom Fields.


The dotCMS folder structure provides a natural hierarchical structure that you can use to categorize your pages and content.

  • Pages and content can be placed in specific folders and folder hierarchies to categorize it.
  • By default, pages and content in a folder display the folder hierarchy in the browser URL when accessed from the front-end.
  • You may create queries to pull content from specific folders and sub-folders, allowing you to pull all content related to a particular folder in the same way you can pull all content for a category, tag, or relationship.

All pages and files you add to your site must be placed in a folder. In addition, content of any Content Type which has been given a Site or Folder field is also placed in a specific folder, allowing you to categorize individual content items by folder location as you would pages or files.

Standard Content Type Fields

The simplest method to label and categorize content is to create fields in your Content Type that allow your content creators to select specific labels which apply to an individual content item.

  • Select Fields allow you to specify a simple list of labels, and allow content creators to select a single label from the list for each item.
  • Multi-Select Fields also allow you to specify a simple list of labels, but allow content creators to select any number of labels for a single piece of content.
  • Radio Buttons can be used in the same way as a Select field, and Checkboxes can be used in the same way as a Multi-Select field.
    • Both the way the list of values are entered and the choices available to content creators are the same; the only difference is in how the labels are displayed.
  • Key/Value Fields can be used similar to Tags, where standard Keys are used, with each content item having different values for each Key.
    • As with Tags, Keys and Values are not pre-defined, and content creators are free to add any new Key, and any Value to any key.

Custom Fields

Custom Fields allow you to create Content Type fields that execute custom code on the back-end form where your content creators edit and submit content. The most common way to use a Custom field as a taxonomy is to pull and display a list of values pulled from another Content Type(in a select or multi-select list, for example), and allow content creators to select one or more values.


The following code, when pasted into the Value property of a custom field, pulls and displays a list of values from a Topics Content Type, which match a specific value of the Subject field Department field.

##Displays a select list.
##   The options in the list are populated by pulling all content items from the "Topics" Content Type
##   with the "Department" field set to "Finance", and then displaying the values of the "Topic Name" field.
<select id="SelectCtlId" dojoType="dijit.form.FilteringSelect" onchange="setCustomValue()">
    #foreach($value in $dotcontent.pull("+structureName:Topics +department:Finance",0,"Topics.topicName"))
            <option value=""></option>

        <option value="$value.topicName" #if($topicTitle == $value.topicName)selected#end>$value.topicName</option>

    function setCustomValue(){
      //Get the value of the select field
      var y = dijit.byId("SelectCtlId").getValue();

      // Set the custom field value (for the field named "DepartmentTopic")
      dojo.byId("departmentTopic").value = y;

Combining and Comparing Taxonomies

You are not limited to using only one taxonomy on your site. On most sites a combination of multiple taxonomies are used, depending on the site needs and the Content Types used. To help you better plan and implement the taxonomies for your site, the following table outlines the main differences among the different taxonomies:

MethodDefined byPractical
HierarchyChoice of
Orderable per
Content Object
to 1
Reuse on
CategoriesAdministrators30 2YesNoNoNoYesYesYesNoYes
Tags 1Content CreatorsNoneNoNoNoNoYesYesNoNoYes
RelationshipsAdministrators100 3YesYesYesYesYesYesYesYesYes
FoldersDepends on
Standard FieldsAdministrators20 4NoYesNoYesYesYesNoNoNo
Custom FieldsDepends on
20 4Yes 5YesYes 5YesYes 5YesYes 5Yes 5Yes


  1. Tags:
  2. Categories:
    • There are no hard limits on the number of Categories, Sub-Categories, or hierarchical levels you can create within a top-level Category.
    • However if you have large numbers of Categories, Sub-Categories, or levels in your Category hierarchy, your content creators may have difficulty finding and selecting the appropriate Categories when adding or editing content.
  3. Relationships:
    • There are no hard limits on the number of content items which can be related to another content item.
    • However if you have large numbers of items related to the same piece of content, displaying or managing all related items may require additional handling in code (such as pagination or block caching) to prevent performance issues.
  4. Fields:
    • There is a hard limit on the number of fields you can add to a Content Type (due to database limitations).
      • You may add a maximum of 25 fields of each field Display Type to a single Content Type.
    • In addition, it is recommended that you limit the number of fields on the main “Content” tab to 20 fields or less, to make sure your content creators can find and enter appropriate values for all fields.
    • If you need additional fields, it is recommended that you use Tab Divider fields to separate groups of related fields into separate tabs to help your content creators find and manage the data in all of the fields.
  5. Depends on implementation

On this page


We Dig Feedback

Selected excerpt: