Dialog Schema

The dialog schema defines the configurable properties of a component. This guide covers all field types, validation, and best practices.

The dialog.json file defines the component's configurable properties:

Top-level properties:

• schemaVersion: Schema version (currently "1.0")
• fields: Array of field definitions

Single-line text input:

Properties:

• type: "text"
• name: Unique field identifier (used in template markers)
• label: Display label shown to users
• required: true or false
• defaultValue: Default value (optional)
• placeholder: Placeholder text (optional)
• maxLength: Maximum character count (optional)

Use cases: Titles, names, short labels

Multi-line text input:

Properties:

• type: "textarea"
• rows: Number of visible rows (optional, default: 3)
• maxLength: Maximum character count (optional)

Use cases: Descriptions, summaries, multi-line content

WYSIWYG editor for formatted text:

Properties:

• type: "richtext"
• toolbar: Array of enabled toolbar buttons (optional)

Toolbar options:

• bold, italic, underline, strikethrough
• heading, paragraph, blockquote
• link, unlink
• bulletList, orderedList
• undo, redo

Use cases: Article content, formatted descriptions, blog posts

Numeric input:

Properties:

• type: "number"
• min: Minimum value (optional)
• max: Maximum value (optional)
• step: Increment step (optional, default: 1)

Use cases: Counts, quantities, numeric settings

Checkbox for true/false values:

Properties:

• type: "boolean"
• defaultValue: true or false

Use cases: Feature toggles, visibility flags

Dropdown selection:

Properties:

• type: "select"
• options: Array of { value, label } objects

Use cases: Predefined choices, alignment, size options

Image upload with alt text:

Properties:

• type: "image"
• defaultValue: Object with src and alt properties

Value format: The field value is stored as JSON:

In templates: Access as {{heroImage.src}} and {{heroImage.alt}}

Use cases: Images, photos, graphics

Link to another page in the site:

Properties:

• type: "pageLink"

Value format: The field value is a page slug (e.g., /about)

Use cases: Internal links, related content, navigation

Required fields must have a non-empty value:

Users cannot save the component without filling required fields.

Default values are used when the field is first added:

Best practices:

• Provide sensible defaults for optional fields
• Use empty string "" for text fields with no default
• Use false for boolean fields that default to off

Limit text field length:

Users see a character counter and cannot exceed the limit.

Constrain numeric values:

Show fields conditionally based on other field values:

Properties:

• showIf.field: Name of the field to check
• showIf.equals: Value that triggers visibility

Behavior:

• Field is hidden when condition is not met
• Field value is preserved when hidden
• Required validation only applies when field is visible

Organize related fields visually:

The CMS validates dialog schemas on upload:

• schemaVersion must be present and equal to "1.0"
• fields or fieldGroups must be present
• Each field must have type, name, and label

• Must be unique within the schema
• Must contain only alphanumeric characters and underscores
• Must start with a letter
• Cannot be empty

Valid: heading, button_text, showImage Invalid: 123heading, button-text, show image

• Must be one of: text, textarea, richtext, number, boolean, select, asset, icon, image, page-link
• Unknown types are rejected

• asset — a single image chosen from the asset library (DAM) or uploaded. The editor shows a thumbnail with a select/upload button; the stored value is the image URL string (use it directly in the template, e.g. {{src}}).
• icon — a single Font Awesome icon chosen from a picker that browses the full Font Awesome Free catalogue (search by name or synonym, filter by solid/regular/brands). The stored value is the icon's class pair, e.g. fa-solid fa-star; render it directly in the template with <i class="{{fieldName}}" aria-hidden="true"></i>. The published page loads the Font Awesome stylesheet automatically when it contains at least one icon.
• page-link — a link destination (also accepts the alias link). The editor lets the author type a URL, click Page to browse the site's page tree and link to an internal page (stored as /path), or click Asset to browse the asset store and link to any uploaded asset — images, PDFs, documents, etc. (stored as the asset URL, e.g. /assets/docs/cv.pdf).

• select fields must have an options array
• Each option must have value and label properties
• At least one option is required

• image fields must have defaultValue as an object with src and alt properties
• Both properties must be strings (can be empty)

• Clear labels: Use descriptive, user-friendly labels
• Helpful placeholders: Provide examples in placeholders
• Logical order: Order fields in a natural sequence
• Group related fields: Use field groups for complex components

• Mark required fields: Only mark truly required fields
• Set reasonable limits: Use maxLength, min, max appropriately
• Provide defaults: Set sensible defaults for optional fields
• Test validation: Try invalid inputs to verify validation works

• Keep it simple: Avoid complex conditional logic
• Test thoroughly: Verify conditional fields show/hide correctly
• Document behavior: Explain conditional logic in field labels or descriptions

• Limit rich text: Rich text fields are heavier than plain text
• Optimize images: Encourage users to upload optimized images
• Avoid too many fields: Keep dialogs focused and manageable

• Component Structure — Overall component structure
• Templating Syntax — Use field values in templates
• Validation Rules — Validation requirements
• Component Example — Complete working example