Component Declaration Schema Reference

The Hyvä CMS Component Declaration JSON Schema defines the structure and validation rules for declaring custom components in Hyvä CMS. This schema ensures that component declarations follow a consistent format, making them compatible with the Hyvä CMS Liveview editor. Component declarations control how components appear in the editor interface, what fields content editors can configure, and how the component data is validated.

When you create a custom component for Hyvä CMS, you must provide a JSON declaration file that conforms to this schema. The schema validates component identifiers, field types, field groups, template paths, and configuration options. Hyvä CMS uses this declaration to generate the editor interface dynamically, ensuring content editors see the correct input fields with appropriate validation rules.

Warning

This documentation may not reflect the latest schema changes or your installed version of Hyvä CMS. Always refer to the schema file in your vendor directory at vendor/hyva-themes/magento2-hyva-cms/src/liveview-editor/etc/hyva_cms/jsonschema/component-declaration.json for the most up-to-date information.

Tip

Hyvä CMS provides helpful exceptions in Developer mode when schema validation fails. These exceptions identify the exact location and nature of schema violations, making it easy to fix declaration errors quickly.

A complete example of a component declaration JSON structure appears at the end of this document in the Complete Button Component Example section.

Schema Specification

The Hyvä CMS Component Declaration Schema is based on JSON Schema Draft 2020-12 and uses the schema identifier hyva-liveview://schema/component-declaration.json. The root structure of every component declaration file is a JSON object where each top-level key represents a unique component identifier. Each component identifier maps to a component declaration object that defines the component's properties, fields, and behavior.

Schema Version: JSON Schema Draft 2020-12
Schema ID: hyva-liveview://schema/component-declaration.json
Root Data Type: Object (keys are component identifiers, values are component declarations)

Component Identifier

The component identifier is the unique string key that identifies each component declaration within a component declaration JSON file. Each component identifier must be unique across all component declarations in your Hyvä CMS installation.

Component identifier validation rules ensure consistency and compatibility:

Minimum length: Must be at least 3 characters long
Allowed characters: Only letters (a-z, A-Z), numbers (0-9), dashes (-), and underscores (_) are permitted
Format: String value serving as the JSON object key for the component declaration

Valid examples: button, hero_banner, product_card, cta_button_v2

Invalid examples: ab (too short), my component (contains space), button! (contains special character)

Main Component Properties

Each component declaration object contains properties that define the component's metadata, behavior, and field structure. These properties control how the component appears in the Hyvä CMS Liveview editor, which template file renders the component, and how the component interacts with other components through parent-child relationships.

label (Required)

The label property defines the human-readable display name for the component in the Hyvä CMS editor interface. Content editors see this label when browsing available components to add to a page or when viewing a component in the page structure tree. The label should clearly describe the component's purpose.

Type: String
Required: Yes (except when the component is disabled)
Example: "Button", "Hero Banner", "Product Card"

disabled (Optional)

The disabled property allows you to temporarily remove a component from the Hyvä CMS editor without deleting the component declaration. When disabled is set to true, the component will not appear in the editor's component selection interface, and content editors cannot add new instances of the disabled component to pages. Existing instances of the disabled component in saved pages continue to function.

Type: Boolean
Default: false
Use case: Temporarily hide deprecated components while maintaining backward compatibility

category (Optional)

The category property organizes components into logical groups in the Hyvä CMS editor component selection interface. Components with the same category value appear together in the editor, making it easier for content editors to find related components. The category string can be any descriptive text.

Type: String
Default: "Other"
Examples: "Layout", "Content", "Commerce", "Marketing"

template (Optional)

The template property specifies which PHTML template file renders the component on the frontend. Hyvä CMS uses Magento's template path format [Vendor]_[Module]::[path].phtml. If omitted, Hyvä CMS automatically generates a default template path based on the component identifier: [Vendor]_[Module]::elements/[component-identifier].phtml.

Type: String or Boolean
Format: [Vendor]_[Module]::[template-path].phtml
Special value: Set to false to indicate the component has no standalone template (useful for child components rendered within their parent's template, such as list items in a list component)
Default: [Vendor]_[Module]::elements/[component-identifier].phtml (auto-generated)
Example: "Vendor_Module::elements/button.phtml"

icon (Optional)

The icon property specifies the image file displayed alongside the component in the Hyvä CMS editor component selection interface. Icons help content editors visually identify components quickly. Hyvä CMS supports common image formats including SVG (recommended for scalability), PNG, JPG, and WebP.

Type: String
Format: [Vendor]_[Module]::[path].(jpg|jpeg|png|gif|webp|svg|avif)
Default: Hyva_CmsLiveviewEditor::images/components/default.svg
Recommended: SVG format for crisp display at all sizes
Example: "Vendor_Module::images/components/button.svg"

children (Optional)

The children property declares that the component can contain child components, creating a parent-child component relationship. When you add a children property to a component declaration, Hyvä CMS adds a special children field to the component in the editor. Content editors can then nest other components inside the parent component. You can set children to true for basic child support, or provide an object with a config property to control which child components are accepted.

Type: Boolean or Object
Location: Must be declared at the root level of the component declaration, not within content, design, or advanced groups
Simple usage: Set to true to enable children with no restrictions
Advanced usage: Set to an object containing a config property to specify which components can be children (see config property for details)
Example: "children": true or "children": { "config": { "accepts": ["button", "icon"] } }

require_parent (Optional)

The require_parent property restricts a component so that content editors can only add the component as a child of another component. Components with require_parent set to true do not appear in the top-level component selection interface; they only appear when adding children to a parent component that accepts them. This property is useful for components that only make sense in a specific context, such as tab panels that belong to a tabs component or list items that belong to a list component.

Type: Boolean
Default: false
Use case: Child-only components like list items, tab panels, accordion items
Example: A usp_item component that only makes sense inside a usp_list parent

content, design, advanced (Optional)

The content, design, and advanced properties are field group objects that organize component fields by their purpose in the Hyvä CMS editor. Each field group object contains field declarations that define the editable properties content editors can configure. The editor presents these field groups as separate sections or tabs, helping content editors understand the purpose of each field.

Type: Object (each property is a field declaration object)
content: Contains fields for the component's main content (text, images, links, etc.)
design: Contains fields for visual styling (colors, spacing, alignment, etc.)
advanced: Contains fields for technical configuration (CSS classes, data attributes, conditional display rules)
Naming convention: Field identifiers within these groups must be unique across all three groups

custom_properties (Optional)

The custom_properties property is a reserved array that allows developers and integration partners to extend the component declaration schema with additional properties not defined in the core schema. Hyvä CMS ignores this property during validation, allowing custom tooling or integrations to store additional metadata alongside component declarations.

Type: Array
Purpose: Reserved for custom extensions and third-party integrations
Note: Not used by core Hyvä CMS functionality

Component Field Declarations

Component field declarations define the editable properties that content editors can configure in the Hyvä CMS Liveview editor. Each field declaration appears within one of the three field groups (content, design, or advanced) and specifies the field's data type, label, validation rules, and behavior. Hyvä CMS uses field declarations to generate the appropriate input controls in the editor interface and to validate field values.

Field identifiers must be unique across all field groups within a component declaration. If you declare the same field identifier in multiple groups (for example, a title field in both content and design), Hyvä CMS will throw an exception in Developer mode indicating the duplicate field identifier. This uniqueness requirement ensures that field values can be unambiguously accessed in component templates.

Field Declaration Properties

Field declarations are objects within the content, design, or advanced field groups. Each field declaration consists of a field identifier (the object key) and a field configuration object (the object value) containing the field's properties.

includes (Optional)

The includes property is a special field group property that imports field declarations from an external JSON file. This allows you to reuse common field sets across multiple components, such as standard design properties (spacing, background color) or advanced properties (CSS classes, custom attributes). When Hyvä CMS processes a field group containing an includes property, the specified file's field declarations are merged into the current field group.

Type: String or Array of Strings
Format: [Vendor]_[Module]::[path/to/file].json
Location: Declared within a field group object (content, design, or advanced), not within individual field declarations
Use case: Share common field sets like default_design.json or default_advanced.json across multiple components
Example: "includes": "Hyva_CmsBase::etc/hyva_cms/default_design.json"

Field Identifier

The field identifier is the unique string key that identifies each field within a component declaration. Hyvä CMS uses the field identifier to reference field values in component templates and to generate unique input element IDs in the editor. Field identifiers follow the same naming rules as component identifiers.

Type: String (used as the JSON object key for the field configuration)
Minimum length: Must be at least 3 characters long
Allowed characters: Only letters (a-z, A-Z), numbers (0-9), dashes (-), and underscores (_) are permitted
Uniqueness: Must be unique across all field groups within the component declaration
Examples: text, button-_ink, background_color, css_class

Field Configuration

Each field configuration object defines how the field behaves in the Hyvä CMS editor and what type of data the field stores. The field configuration properties control the input type, validation rules, default values, and conditional visibility.

type (Required)

The type property determines which input control Hyvä CMS displays in the editor and what kind of data the field stores. Each field type corresponds to a specific editor widget with appropriate validation and data handling. For example, the color type displays a color picker, the image type displays an image upload interface, and the richtext type displays a WYSIWYG text editor.

Type: String
Required: Yes
Allowed Values: boolean, color, date, datetime, html, image, link, multiselect, number, range, products, richtext, select, searchable_select, text, text-align, textarea, variant, widget, custom_type
Note: Use custom_type for field types implemented by custom extensions; specify the custom type name in the custom_type property

custom_type (Optional)

The custom_type property specifies the name of a custom field type when the type property is set to "custom_type". Custom field types allow developers to extend Hyvä CMS with new input controls and data types beyond the built-in field types. The custom type name should match a field type registered through Hyvä CMS's field type extension mechanism.

Type: String
Required: Only when type is set to "custom_type"
Use case: Custom input controls for specialized data types (e.g., font pickers, gradient editors, custom entity selectors)

label (Required)

The label property defines the human-readable text displayed next to the field input in the Hyvä CMS Liveview editor form. Content editors see this label when configuring component properties. The label should clearly describe what the field controls.

Type: String
Required: Yes
Example: "Button Text", "Background Color", "Maximum Items"

default_value (Optional)

The default_value property specifies the initial value assigned to the field when a content editor first adds the component to a page. Default values provide sensible starting points and can reduce the configuration burden for common use cases. The data type of the default value should match the field's type (string for text fields, boolean for boolean fields, etc.).

Type: Any (must match the field's type)
Example: For a text field: "Click me", for a boolean field: true, for a number field: 3

show_if (Optional)

The show_if property defines conditional visibility rules that control when the field appears in the editor. The field is displayed only when another field (specified by the referenced field identifier) has a value matching one of the values in the specified array. This allows you to create dynamic forms that show or hide fields based on other field values.

Type: Object with field identifier keys and array values
Format: { "field-identifier": ["value1", "value2"] }
Example: { "enable-link": [true] } shows the current field only when the enable-link field is true

Tip

Use show_if and hide_if sparingly. Complex conditional logic can create forms that are difficult for content editors to understand and maintain. Consider whether multiple simpler components might be clearer than one component with many conditional fields.

hide_if (Optional)

The hide_if property defines conditional visibility rules that control when the field is hidden in the editor. The field is hidden when another field (specified by the referenced field identifier) has a value matching one of the values in the specified array. This provides the inverse behavior of show_if.

Type: Object with field identifier keys and array values
Format: { "field-identifier": ["value1", "value2"] }
Example: { "layout-type": ["simple"] } hides the current field when the layout-type field is set to "simple"

Tip

Prefer show_if over hide_if when possible, as explicitly showing fields is often clearer than hiding them. Use hide_if when a field should be visible by default but hidden in specific cases.

attributes (Optional)

The attributes property allows you to specify HTML attributes and validation rules for field input elements. Hyvä CMS applies these attributes to the generated input controls in the editor, enabling standard HTML5 validation (required, min, max, pattern) as well as custom validation using data attributes. Attributes control input behavior, provide placeholder text, display help text, and enforce data quality rules.

Type: Object containing attribute name-value pairs
Supported value types: string, number, integer, boolean, null, or array

Common HTML Attributes:

class (string): CSS classes applied to the input element
placeholder (string): Placeholder text displayed in empty inputs
required (boolean): Marks the field as required; prevents saving without a value
pattern (string): Regular expression for input validation
min (string): Minimum value for number/range fields or minimum length for text fields
max (string): Maximum value for number/range fields or maximum length for text fields
minlength (string): Minimum text length (alternative to min for text fields)
maxlength (string): Maximum text length (alternative to max for text fields)
step (string): Step increment for number/range fields
comment (string): Help text displayed below the field in the editor

Custom Validation with Data Attributes:

The data- prefixed attributes provide validation without affecting browser API behavior. Use these for client-side validation rules that don't rely on HTML5 validation:

data-required (boolean): Validates required status without triggering browser required validation
data-min (string): Validates minimum value/length without triggering browser min validation
data-max (string): Validates maximum value/length without triggering browser max validation
data-pattern (string): Validates pattern matching without triggering browser pattern validation

Custom Validation Messages:

You can provide user-friendly validation error messages that content editors see when validation fails:

data-required-msg (string): Message displayed when a required field is empty
data-min-msg (string): Message displayed when value is below min or minlength
data-max-msg (string): Message displayed when value exceeds max or maxlength
data-pattern-msg (string): Message displayed when value doesn't match the pattern

Note

Both data-min-msg and data-max-msg work for min, max, minlength, and maxlength validation. Hyvä CMS automatically applies the appropriate message based on which validation rule fails.

options (Optional)

The options property defines the available choices for selection field types (select, multiselect, searchable_select). Hyvä CMS uses options to populate dropdown menus, multi-select lists, and searchable select inputs in the editor. You can provide options as a static array of choice objects or as a reference to a PHP class that generates options dynamically.

Type: Array of objects, or String (PHP class reference)

Static Options Array:

Provide an array of choice objects, where each object contains a label (displayed to content editors) and a value (stored in the component data). Use static options for fixed choice lists that don't change.

"options": [
  {
    "label": "Heading lv1",
    "value": "h1"
  },
  {
    "label": "Heading lv2",
    "value": "h2"
  },
  {
    "label": "Heading lv3",
    "value": "h3"
  }
]

Dynamic Options from PHP Class:

Provide a fully qualified PHP class name (with escaped backslashes) that implements OptionSourceInterface. Hyvä CMS calls the class to retrieve options dynamically at runtime. You can optionally append ::methodName to call a specific method instead of the default toOptionArray() method. Use dynamic options when choices depend on system configuration, database data, or other runtime conditions.

"options": "Vendor\\Module\\Model\\Source\\HeadingLevels"

"options": "Vendor\\Module\\Model\\Source\\Options::getCustomOptions"

config (Optional)

The config property provides configuration settings that control component behavior and parent-child relationships. For components with a children property, the config object specifies which child components are allowed, which are excluded, and how many children can be added. This enables you to create structured component hierarchies with validation rules.

Type: Object
Use case: Primarily used with the children property to control child component relationships

Config Properties for Children:

accepts (array of strings): Specifies which component identifiers are allowed as children. Only components in this list can be added as children. If omitted, any component can be a child (unless require_parent prevents it).
excludes (array of strings): Specifies which component identifiers are prohibited as children. Components in this list cannot be added as children even if they would otherwise be allowed.
max_children (integer): Specifies the maximum number of child components allowed. Content editors cannot add more children once this limit is reached.

The following example shows a component that accepts only button, icon, and heading components as children, explicitly excludes text components, and allows a maximum of 3 children:

"config": {
  "accepts": ["button", "icon", "heading"],
  "excludes": ["text"],
  "max_children": 3
}

custom_properties (Optional)

The custom_properties property is a reserved array that allows developers to extend individual field declarations with additional properties not defined in the core schema. Hyvä CMS ignores this property during validation, allowing custom tooling or extensions to store field-level metadata.

Type: Array
Purpose: Reserved for custom extensions and third-party integrations
Note: Not used by core Hyvä CMS field functionality

Complete Button Component Example

The following example demonstrates a complete button component declaration that uses all the key features of the Hyvä CMS Component Declaration Schema. This button component includes content fields (text and link), design fields (alignment plus shared design properties), and advanced fields (shared from the base module). The example shows how to structure a practical, production-ready component declaration with proper validation, default values, and field organization.

For additional component declaration examples, refer to the Hyva_CmsBase module which contains declarations for various built-in components.

{
  "button": {
    // Component identifier: unique key for this component declaration
    // Metadata properties that control editor appearance
    "label": "Button",
    "category": "Example",
    "template": "Vendor_MyModule::elements/button.phtml",
    "icon": "Vendor_MyModule::images/components/button.svg",

    // Content field group: main editable properties for button content
    "content": {
      "text": {
        // Text field: the button's display text
        "type": "text",
        "label": "Button Text",
        "default_value": "Click me",
        "attributes": {
          // Require button text and provide helpful placeholder
          "required": true,
          "placeholder": "Enter button text"
        }
      },
      "link": {
        // Link field: provides Hyvä's link picker for URL, page, or product selection
        "type": "link",
        "label": "Button Link"
      }
    },

    // Design field group: visual styling properties
    "design": {
      // Include shared design fields from base module (spacing, colors, etc.)
      "includes": "Hyva_CmsBase::etc/hyva_cms/default_design.json",
      "alignment": {
        // Text-align field: provides left/center/right alignment options
        "type": "text-align",
        "label": "Alignment"
      }
    },

    // Advanced field group: technical configuration properties
    "advanced": {
      // Include shared advanced fields from base module (CSS classes, attributes, etc.)
      "includes": "Hyva_CmsBase::etc/hyva_cms/default_advanced.json"
    }
  }
}

Working with Components - Learn how to create component template files and register component declarations
Overriding Existing Components - Customize built-in component declarations and templates

Component Declaration Schema Reference

Schema Specification

Component Identifier

Main Component Properties

label (Required)

disabled (Optional)

category (Optional)

template (Optional)

icon (Optional)

children (Optional)

require_parent (Optional)

content, design, advanced (Optional)

custom_properties (Optional)

Component Field Declarations

Field Declaration Properties

includes (Optional)

Field Identifier

Field Configuration

type (Required)

custom_type (Optional)

label (Required)

default_value (Optional)

show_if (Optional)

hide_if (Optional)

attributes (Optional)

options (Optional)

config (Optional)

custom_properties (Optional)

Complete Button Component Example

Related Topics