Module definition items

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

Depending on your installation of Magnolia, the set of definition registries present in the system may vary. The table below outlines some of the common configuration items, the item’s purpose, and whether it is visible in the Definitions app.

Config item Purpose Visible


optional YAML supported; App descriptor files, defining Apps.


optional YAML supported; Block definitions.

A block is the smallest piece of content in an implementation of the Content editor.



optional Command definitions used with Magnolia command management.


A Magnolia content type is a formal definition for a type of content in Magnolia including the properties the type may contain and its relationships to other types of content.

A content type is configured in a content type definition that includes the data source definition and the model definition.


optional YAML supported; Dashboard definitions for analytics dashboards.


optional YAML supported; Supplies the raw data for dashboards.


optional YAML supported; Dialog definitions for content editing.


optional YAML supported; Allows use of the E-commerce app.


optional YAML supported; Field definitions for Magnolia 5 UI fields.


optional YAML supported; GraphQL type definitions.

The GraphQL module allows you to expose content stored in JCR through GraphQL POST and GET requests.


optional YAML supported; Media Editor definitions.


optional YAML supported; Message view definitions.


optional YAML supported; Renderer definitions. Creating custom renderers for other templating languages such as Velocity is possible.

Magnolia ships with the FreeMarker template renderer.


optional YAML supported; Specifies REST clients that can be used together with the $jsonDatasource in content apps, link fields, or in searchResultSuppliers.

The REST Client app allows you to test REST clients.


optional YAML supported; REST endpoint definitions.


optional; Search result suppliers are responsible for providing search results to the Find Bar’s search result area through the Periscope module.


A site definition contains site-wide configuration such as navigation, common page areas, and JavaScript that you want to load on every page.


optional YAML supported; Template definitions for pages, areas or components.


optional YAML supported; Themes for the site.

A Theme is a collection of resource files that gives a site its visual identity through the use of colors and typography. A theme consists of cascading style sheets (CSS), JavaScript files and an imaging configuration that tells the Imaging module what to do with images for a particular page or component.


optional 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.


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

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 info.magnolia.rendering.template.TemplateDefinition in info.magnolia.rendering.template.registry.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 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 info.magnolia.dirwatch.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

Item YAML file path JCR node path in the config workspace

App descriptor



Command definition



Dialog definition



Field type definition (Magnolia 5 UI)



Media editor definition



Message view definition



Renderer definition



REST endpoint definition



Template definition



Trait definition



Virtual URI mapping definition




DX Core



This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.