This page provides an overview of definition items which can be specified in Magnolia modules.

A definition item is a component configuration for executing tasks in a Magnolia instance. Template definitions, dialog definitions, app definitions (also known as app descriptors), renderer definitions, themes definitions and field definitions are all examples of such definition items.

The majority of these items can be configured via YAML, in which case they are registered in a specific registry. The items registered can be seen in the Definitions app and can be modified through definition decoration. Even though definition items can be configured via JCR in the configuration workspace, configuring them in YAML files is the recommended approach.

Overview of definition items

Configuration item


Visible in the
Definitions app

optional, YAML supported

App descriptor files, defining Apps.




Command definitions used with Magnolia command management.


optional, YAML supported

Dialog definitions for content editing.



optional, YAML supported

Field definitions for Magnolia 5 UI fields.


optional, YAML supported

Media Editor definitions.



optional, YAML supported

Message view definitions.



optional, YAML supported

Renderer definitionsCreating custom renderers for other templating languages such as Velocity is possible.

Magnolia ships with the FreeMarker template renderer.


optional, YAML supported

REST endpoint definitions.



optional, YAML supported

Template definitions for pages, areas or components.



A trait is an attribute or property of a visitor or visit, such as age or gender, that you can use to personalize content.


optional, YAML supported

URI mapping definitions that redirect an incoming request to the actual content location.


Configuring in JCR and in YAML

While all of the configuration items listed above can be stored as JCR nodes, not all of them have YAML support. The items which cannot be stored yet as YAML files may, however, get YAML support in future Magnolia versions.

We recommend using YAML files for definition items.

Both JCR nodes and YAML files are observed. If a data change is detected, object representations are changed in the associated registries. For instance, a change in a template definition re-registers or updates the TemplateDefinition in TemplateDefinitionRegistry.

Item definitions from both JCR nodes and YAML files can be decorated with a definition decoration.

JCR nodes

In JCR context, module configuration items are stored as nodes in the configuration workspace. Use the Configuration app to add, edit or delete JCR-based configuration. The items ares stored under /modules/<module‑name>, for instance under /modules/myModule/templates. JCR configuration nodes are observed using functions provided by the Observation module.


  • All configuration items are supported.
  • Changes can be published (activated) to other instances.
  • The extends mechanism is supported.

YAML files

In a module, YAML configuration files reside in their corresponding folders. For example, <module‑name>/templates is the folder for the templates. To add, edit or delete a YAML file, use any text editor of your choice. Many modern editors such as Brackets or Sublime Text support YAML syntax highlighting.

Directories containing YAML-based configuration data are observed using the DirectoryWatcherService.


  • Text files are human readable and easy to compare, which makes collaboration better.

  • No need to export. Files are already part of the project lifecycle.

  • No need for version handlers for updates.
  • Uninstalling is easy.
  • The include mechanism is supported.

Location of configuration items

ItemYAML file pathJCR node path in the config workspace
App descriptor $magnolia.resources.dir/<module‑name>/apps /modules/<module‑name>/apps
Command definition /modules/<module‑name>/commands
Dialog definition $magnolia.resources.dir/<module‑name>/dialogs /modules/<module‑name>/dialogs
Field type definition (Magnolia 5 UI) $magnolia.resources.dir/<module‑name>/fieldTypes /modules/<module‑name>/fieldTypes
Media editor definition $magnolia.resources.dir/<module‑name>/mediaEditors /modules/<module‑name>/mediaEditors
Message view definition $magnolia.resources.dir/<module‑name>/messageViews /modules/<module‑name>/messageViews
Renderer definition $magnolia.resources.dir/<module‑name>/renderers /modules/<module‑name>/renderers
REST endpoint definition $magnolia.resources.dir/<module‑name>/restEndpoints /modules/<module‑name>/restEndpoints
Template definition$magnolia.resources.dir/<module‑name>/templates /modules/<module‑name>/templates
Trait definition /modules/<module‑name>/traits
Virtual URI mapping definition$magnolia.resources.dir/<module‑name>/virtualUriMappings /modules/<module‑name>/virtualUriMappings
#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels