Tagging allows content to be categorized and organized. Tags can be classified by a namespace and a taxonomy. For detailed information about using tags:
This article focuses on the underlying framework which supports tagging in AEM and how to use it as a developer.
To tag content and use the AEM Tagging infrastructure :
cq:Tagunder the taxonomy root node.
NodeTypemust include the
TagIDis added to the content node’s
cq:tagsproperty and resolves to a node of type
The declaration of a tag is captured in the repository in a node of type
sky) or represent a hierarchical taxonomy (for example,
fruit/apple, meaning both the generic fruit and the more specific apple).
TagID, when present.
The tagging framework also restricts authors and site visitors to use only specific, predefined tags.
TagIDalways includes a namespace.
jcr:titleproperty (the Title to display in the UI) is optional.
jcr:descriptionproperty is optional.
TagID identifies a path which resolves to a tag node in the repository.
TagID is a shorthand
TagID starting with the namespace or it can be an absolute
TagID starting from the taxonomy root node.
When content is tagged, if it does not yet exist, the
cq:tags property is added to the content node and the
TagID is added to the property’s
String array value.
TagID consists of a namespace followed by the local
TagID. Container tags have subtags that represent a hierarchical order in the taxonomy. Subtags can be used to reference tags same as any local
TagID. For example, tagging content with
fruit is allowed, even if it is a container tag with subtags, such as
The taxonomy root node is the base path for all tags in the repository. The taxonomy root node must not be a node of type
In AEM, the base path is
/content/cq:tags and the root node is of type
Namespaces let you group things. The most typical use-case is to have a namespace per site (for example, public versus internal) or per larger application (for example, Sites or Assets), but namespaces can be used for various other needs. Namespaces are used in the user interface to show only the subset of tags (that is, tags of a certain namespace) that is applicable to the current content.
The tag’s namespace is the first level in the taxonomy subtree, which is the node immediately below the taxonomy root node. A namespace is a node of type
cq:Tag whose parent is not a
cq:Tag node type.
All tags have a namespace. If no namespace is specified, the tag is assigned to the default namespace, which is
default, that is,
/content/cq:tags/default. The Title defaults to
Standard Tagsin such cases.
A container tag is a node of type
cq:Tag containing any number and type of child nodes, which makes it possible to enhance the tag model with custom metadata.
Furthermore, container tags (or super-tags) in a taxonomy serve as the subsummation of all subtags. For example, content tagged with
fruit/apple is considered tagged with
fruit, too. That is, searching for content tagged with
fruit would also find the content tagged with
If the tag ID contains a colon (
:), the colon separates the namespace from the tag or subtaxonomy, which are then separated with normal slashes (
/). If the tag ID does not have a colon, the default namespace is implied.
The standard and only location of tags is below
Tags referencing non-existing paths or paths that do not point to a
cq:Tag node are considered invalid and are ignored.
The following table shows some sample
TagIDs, their elements, and how the
TagID resolves to an absolute path in the repository:
||Namespace||Local ID||Container Tags||Leaf Tag||Repository Absolute Tag Path|
When the tag includes the optional title string
jcr:title, it is possible to localize the title for display by adding the property
For more details, see the following:
Tags exist as nodes in the repository under the taxonomy root node. Allowing or denying authors and site visitors to create tags in a given namespace can be achieved by setting appropriate ACLs in the repository.
Denying read permissions for certain tags or namespaces controls the ability to apply tags to specific content.
A typical practice includes:
tag-administratorsgroup/role write access to all namespaces (add/modify under
/content/cq:tags). This group comes with AEM out-of-the-box.
For application developers to attach tagging to a content type, the node’s registration (CND) must include the
cq:Taggable mixin or the
cq:OwnerTaggable mixin, which inherits from
cq:Taggable, is intended to indicate that the content can be classified by the owner/author. In AEM, it is only an attribute of the
cq:PageContent node. The
cq:OwnerTaggable mixin is not required by the tagging framework.
It is recommended to only enable tags on the top-level node of an aggregated content item (or on its
jcr:content node). Examples include:
cq:Page) where the
jcr:contentnode is of type
cq:PageContent, which includes the
cq:Asset) where the
jcr:content/metadatanode always has the
Node Type definitions exist in the repository as CND files. The CND notation is defined as part of the JCR documentation.
The essential definitions for the Node Types included in AEM are as follows:
[cq:Tag] > mix:title, nt:base orderable - * (undefined) multiple - * (undefined) + * (nt:base) = cq:Tag version [cq:Taggable] mixin - cq:tags (string) multiple [cq:OwnerTaggable] > cq:Taggable mixin
cq:tags property is a
String array used to store one or more
TagIDs when they are applied to content by authors or site visitors. The property only has meaning when added to a node which is defined with the
To use AEM tagging functionality, custom developed applications should not define tag properties other than
The following is a description of the effects in the repository when moving or merging tags using the Tagging console.
When tag A is moved or merged into tag B under
cq:movedTo points to tag B.
This property means that tag A has been moved or merged into tag B.
Moving tag B updates this property accordingly.
Tag A is therefore hidden and is only kept in the repository so it can resolve tag IDs in content nodes pointing to tag A.
The tag garbage collector removes tags like tag A once no more content nodes point to them.
A special value for the
cq:movedTo property is
nirvana, which is applied when the tag is deleted but cannot be removed from the repository because there are subtags with a
cq:movedTo that must be kept.
cq:movedTo property is only added to the moved or merged tag if either of these conditions are met:
cq:backlinks keeps the references in the other direction. That is, it keeps a list of all the tags that have been moved to or merged with tag B.
This functionality is mostly required to keep
cq:movedTo properties up to date when tag B is moved/merged/deleted as well or when tag B is activated, in which case all its backlinks tags must be activated as well.
cq:backlinks property is only added to the moved or merged tag if either of these conditions are met:
cq:tags property of a content node involves the following resolution:
/content/cq:tags, no tag is returned.
cq:movedToproperty set, the referenced tag ID is followed.
cq:movedToproperty, the tag is read.
To publish the change when a tag has been moved or merged, the
cq:Tag node and all its backlinks must be replicated. This replication is automatically done when the tag is activated in the tag administration console.
Later updates to the page’s
cq:tags property automatically clean up the old references. The clean up is triggered because resolving a moved tag through the API returns the destination tag, thus providing the destination tag ID.