DocumentationAEM as a Cloud ServiceUser Guide

Component Definition component-definition

Last update: Tue Sep 09 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Applies to:
  • Experience Manager as a Cloud Service

CREATED FOR:

  • Admin
  • Developer

Understand the JSON contract between the component definition and the Universal Editor in detail.

Overview overview

The component-definition.json file defines the components available to your content authors for the project. This document explains in detail the purpose of this file and how the Universal Editor uses it to present your authors with page authoring components.

TIP
For an overview of the content modeling process, please see the document Content Modeling for WYSIWYG Authoring with Edge Delivery Services Projects.
TIP
You do not need to create your own component-definition.json file from scratch. The project boilerplate that you use to bootstrap your project contains a fully-functioning component-definition.json file that you can adapt to your needs.

Example Component Definition example

The following is a complete, but simple component-definition.json as an example.

{
  "groups":[
    {
      "title":"General Components",
      "id":"general",
      "components":[
        {
          "title":"Text",
          "id":"text",
          "model": "text",
          "filter": "texts",
          "plugins":{
            "aem":{
              "page":{
                "resourceType":"wknd/components/text",
                "template":{
                  "text":"Default Text",
                  "name":"Text"
                }
              }
            },
            "aem65":{
              "page":{
                "resourceType":"wknd/components/text",
                "template":{
                  "text":"Default Text",
                  "name":"Text"
                }
              }
            }
          }
        }
      ]
    }
  ]
}

groups groups

groups defines the groups of components that the author sees in the Universal Editor when clicking the Add icon in the properties panel of the editor to add a new component to a page. Groups help organize the components. Common groups might be General Components and Advanced Components.

  • title defines the textual description of the group shown in the editor UI.
  • id uniquely identifies the group.

components components

components defines which components belong to a group.

  • title defines the textual description of the component shown in the UI.

  • id uniquely identifies the component.

    • The component model of the same id defines the fields of the component.
    • Because it is unique it can be used, for example, in a filter definition to determine which components can be added to a container.

  • model defines which model is used with the component.

    • The model is thereby maintained centrally in the component definition and doesn’t need to be specified the instrumentation.
    • This allows you to move components across containers.

  • filter defines which filter should be used with the component.

plugins plugins

plugins defines which plugin is responsible for persisting the component. Common plugins include:

page or cf page-cf

Once the plugin is defined, you need to indicate if it is page-related or fragment-related.

  • page indicates that the component is content on the current page.
  • cf indicates that the component is related to content within a Content Fragment.

page page

If the component is content on the page, you can provide the following information.

  • resourceType defines the Sling resourceType used for rendering the component.
  • template defines optional key/values to be automatically written to the newly-created component and defines which filter and/or model should be applied to the component.
    • Useful for explanatory, sample, or placeholder text.

template template

By providing optional key/value pairs, template can automatically write these to the new component. Additionally, the following optional values can also be specified.

cf cf

If the component is related to content within a Content Fragment, you can provide the following information.

  • name defines an optional name saved to the JCR for the newly-created component.
    • Informative only and not generally shown in the UI as the title is.
  • cfModel defines the Content Fragment model for the newly-created component.
  • cfFolder defines in which folder the Content Fragment shall be created.
  • title defines the title of the new Content Fragment.
  • description defines a description of the new Content Fragment.
  • template defines optional key/values to be automatically written to the newly-created Content Fragment.
    • Useful for explanatory, sample, or placeholder text.

cf Can be Implied cf-implied

If the page is instrumented to point to a reference field, the cf will be assumed.

<div data-aue-resource="urn:aem:/content" data-aue-type="container" data-aue-prop="field"></div>

In such a case, cf is assumed, because the data-aue-prop points to a reference field. Without the data-aue-prop, the Universal Editor will assume page, because in such case the components are not linked via a reference field.

<div data-aue-resource="urn:aem:/content" data-aue-type="container"></div>

Components are simply subnodes below the resource.

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab