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):

component-definition.json — Registers blocks in the UE component palette
component-models.json — Defines property panel fields for each block
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:

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?
The block's CSS file (
```
blocks/<name>/<name>.css
```
) — look for variant-specific styles.
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

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:

json

{
  "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:

json

{
  "id": "<model-id>",
  "fields": [
    {
      "component": "<field-type>",
      "name": "<property-name>",
      "label": "<Display Label>",
      "valueType": "string"
    }
  ]
}

component-filters.json — Add the block ID to the

section

filter's

components

array. For container blocks, also add a new filter entry defining allowed children.

For Distributed Config (creating

blocks/<name>/_<name>.json

Create a single file with all three configs:

json

{
  "definitions": [ ... ],
  "models": [ ... ],
  "filters": [ ... ]
}

Still add the block to the

section

filter in the central

component-filters.json

Step 5: Validate

After generating the config, verify:

ID consistency: The
```
id
```
in the definition matches what's used in
```
component-filters.json
```
. The
```
template.model
```
value matches the
```
id
```
in
```
component-models.json
```
.
Filter registration: The block's ID appears in the
```
section
```
filter's
```
components
```
array (otherwise authors can't add it to pages).
Field names match block JS: The
```
name
```
properties in the model fields should produce HTML that the block's
```
decorate()
```
function can consume.
Semantic collapsing: Paired fields use correct suffixes (e.g.,
```
image
```
/
```
imageAlt
```
, not
```
image
```
/
```
altText
```
unless intentional).
Valid JSON: All three files remain valid JSON after edits.
No duplicate IDs: No model or filter ID conflicts with existing entries.

Reference Files

For detailed information, read these reference files as needed:

references/architecture.md
— How the three files connect, the full AEM→Markdown→HTML pipeline, resource types, field naming conventions, semantic collapsing rules, and RTE filter configuration
references/field-types.md
— Complete reference for all 17 field component types (
```
text
```
,
```
textarea
```
,
```
richtext
```
,
```
reference
```
,
```
aem-content
```
,
```
aem-content-fragment
```
,
```
aem-experience-fragment
```
,
```
aem-tag
```
,
```
select
```
,
```
multiselect
```
,
```
checkbox-group
```
,
```
radio-group
```
,
```
boolean
```
,
```
number
```
,
```
date-time
```
,
```
container
```
,
```
tab
```
), valueType constraints, required properties, field properties, validation types, conditional fields, and option formats
references/examples.md
— Real examples showing Hero (simple), Embed (simple with URL), Cards (container), Teaser (variants), Product Details (key-value), Article (content fragment), Section configuration, Metadata (textarea), Feature Toggles (checkbox-group), and RTE filter configuration

Common Pitfalls

Forgetting to add to section filter: The block won't appear in the author's add menu unless it's in the
```
section
```
filter's components list.
Wrong resourceType: Almost all custom blocks use
```
core/franklin/components/block/v1/block
```
. Don't invent custom resource types.
Mismatched model/filter IDs: The
```
template.model
```
must exactly match the model
```
id
```
, and
```
template.filter
```
must exactly match the filter
```
id
```
.
Choosing the wrong text field type: Use
```
text
```
for single-line strings,
```
textarea
```
for multi-line plain text, and
```
richtext
```
for formatted content. For URLs and page links, use
```
aem-content
```
so authors get the content picker.
Wrong valueType: Most components enforce a specific
```
valueType
```
(e.g.,
```
boolean
```
must use
```
"boolean"
```
,
```
number
```
must use
```
"number"
```
,
```
checkbox-group
```
must use
```
"string[]"
```
). Always include
```
valueType
```
and check the field-types reference for the enforced value.
Container without filter: Container blocks need a
```
filter
```
(not a
```
model
```
) in their template, and a corresponding filter entry in component-filters.json.

ue-component-model

NPX Install

Tags

SKILL.md Content

Universal Editor Component Model Configuration

When to Use

Workflow

Step 1: Understand the Block

Step 2: Determine the Block Type

Step 3: Design the Model Fields

Step 4: Generate the Configuration

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

For Distributed Config (creating
`blocks/<name>/_<name>.json`
):

Step 5: Validate

Reference Files

Common Pitfalls

ue-component-model

NPX Install

Tags

SKILL.md Content

Universal Editor Component Model Configuration

When to Use

Workflow

Step 1: Understand the Block

Step 2: Determine the Block Type

Step 3: Design the Model Fields

Step 4: Generate the Configuration

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

For Distributed Config (creating blocks/<name>/_<name>.json):

Step 5: Validate

Reference Files

Common Pitfalls

For Distributed Config (creating
`blocks/<name>/_<name>.json`
):