/ue-component-model

name: ue-component-model
description: Use this when the user mentions component models, component definitions, component filters, block configuration for the Universal Editor, UE block setup, adding a new block to UE, configuring block properties or block authoring fields, or wants to create an EDS/Franklin block with Universal Editor support, modify block fields, or add a block to the section filter. Covers creating and editing the three JSON files that control how AEM Edge Delivery Services blocks appear and behave in the Universal Editor — component-definition.json, component-models.json, and component-filters.json.
license: Apache-2.0

Universal Editor Component Model Configuration

This skill helps you create or edit the three JSON configuration files that control how AEM Edge Delivery Services (EDS) blocks appear and behave in the Universal Editor (UE):

1. **component-definition.json** — Registers blocks in the UE component palette 2. **component-models.json** — Defines property panel fields for each block 3. **component-filters.json** — Controls where blocks can be placed

When to Use

• Creating a new block that needs UE authoring support
• Adding/modifying fields on an existing block's property panel
• Registering a block so it appears in the author's component palette
• Setting up container blocks with child items
• Adding block variants/style options

Workflow

Step 1: Understand the Block

Before generating any configuration, read and analyze:

1. **The block's JS file** (`blocks/<name>/<name>.js`) — understand what content the `decorate(block)` function expects:

• What does it read from the block div? (images, links, text, classes)
• Does it expect a flat structure or rows of items?
• Does it use `block.querySelector('a')` (links/URLs), `block.querySelector('picture')` (images), etc.?
• Does it check for CSS classes/variants?

2. **The block's CSS file** (`blocks/<name>/<name>.css`) — look for variant-specific styles.

3. **Existing config** — check if entries already exist:

• Search `component-definition.json` for the block ID
• Search `component-models.json` for the model ID
• Search `component-filters.json` for the block in the `section` components list
• Check for a `blocks/<name>/_<name>.json` distributed config file

Step 2: Determine the Block Type

Based on the JS analysis:

• **Simple block**: One component with its own fields. Most blocks are this type.
• Example: Hero, Embed — single model, no children

• **Container block**: Has repeatable child items (cards, slides, tabs).
• Clue: JS iterates over `block.children` or creates items from rows
• Needs: container definition + item definition + filter

• **Key-value block**: Configuration-style block (2-column key-value pairs).
• Clue: Each property is independent, not a grid of content
• Needs: `"key-value": true` in template

Step 3: Design the Model Fields

Map the block's content expectations to component model fields. Read [references/field-types.md](references/field-types.md) for the full field type reference.

**Common field mappings:**

| Block expects... | Use component type | Notes | |-----------------|-------------------|-------| | An image | `reference` (name: `image`) | Pair with `text` field named `imageAlt` | | A URL/link | `aem-content` (name: `link` or `url`) | For page links and external URLs | | Rich text content | `richtext` | For formatted text with headings, lists, links | | Plain text (single line) | `text` | For titles, labels, short strings | | Plain text (multi-line) | `textarea` | For descriptions, notes, long text without formatting | | Heading level choice | `select` with h1-h6 options | Name it `titleType` to auto-collapse with title | | Style variants | `multiselect` (name: `classes`) | Values become CSS classes on block div | | Multiple toggles | `checkbox-group` | For multiple independent boolean options | | Boolean toggle | `boolean` | For show/hide options | | Number value | `number` | For counts, limits | | Content Fragment | `aem-content-fragment` | For CF-driven blocks | | Experience Fragment | `aem-experience-fragment` | For reusable content+layout fragments | | Content tags | `aem-tag` | For categorization via AEM tag picker |

**Field naming rules (semantic collapsing):**

• `image` + `imageAlt` → collapsed into `<picture><img alt="...">`
• `link` + `linkText` + `linkTitle` + `linkType` → collapsed into `<a href="..." title="...">text</a>` with optional class
• `title` + `titleType` → collapsed into `<h2>title</h2>` (level from titleType)
• Fields prefixed with `group_` (underscore separator) are grouped into a single cell

Step 4: Generate the Configuration

Generate entries for all three files. The approach depends on whether the project uses centralized or distributed config.

**Check for distributed config pattern**: If the block directory contains `_<blockname>.json` files (e.g., `blocks/hero/_hero.json`), create a distributed config file instead of editing the central files.

For Centralized Config (editing the three root JSON files):

**component-definition.json** — Add to the `"Blocks"` group's `components` array:

{
  "title": "<Block Display Name>",
  "id": "<block-id>",
  "plugins": {
    "xwalk": {
      "page": {
        "resourceType": "core/franklin/components/block/v1/block",
        "template": {
          "name": "<Block Name>",
          "model": "<model-id>"
        }
      }
    }
  }
}

For container blocks, add both the container AND item definitions. The container gets `"filter"` instead of `"model"`, and the item uses `"core/franklin/components/block/v1/block/item"` as resourceType.

For key-value blocks, add `"key-value": true` to the template.

Template can include default values for any model field (e.g., `"titleType": "h3"`, `"classes": ["light"]`).

**component-models.json** — Add a new model entry:

{
  "id": "<model-id>",
  "fields": [
    {
      "compone