Component Declaration JSON Schema

Hyvä Commerce is an 'Early Access' product currently under development.

Early Access means that not all features of Hyvä Commerce are fully completed or released, and many areas are still under heavy development and may change. However, it means you can get your hands on everything currently available and being worked on, with a license. Find out more on our Early Access page.

This guide explains the JSON schema used to declare components in Hyva CMS. It covers the key elements and rules to help you create well-structured, consistent components.

Where possible, Hyvä CMS, will give you an exception in Developer mode to tell you if you make a mistake, so you can identify and fix quickly and easily.

Warning

This documentation may not reflect the latest schema changes before the first general release. Always refer to the component-declaration.json schema file for the most up-to-date information.

For a complete example JSON used for component declaration see below.

Overview

Schema Version: JSON Schema Draft 2020-12
Schema ID: hyva-liveview://schema/component-declaration.json
Data Type: Object

Component Identifier

Definition: A unique key for each component declaration
Rules:
- Must be a string at least 3 characters long
- Only letters, numbers, dashes, or underscores are allowed

Main Component Properties

Within each component declaration object, you can define the following:

label (Required)

Type: String
Purpose: The label of the component, providing a user-friendly name in the Hyvä CMS editor
Note: Not required if the component is disabled.

disabled (Optional)

Type: Boolean
Purpose: If set to true, the component will be disabled in the Hyvä CMS editor
Default: false

category (Optional)

Type: String
Purpose: Groups components in the Hyvä CMS editor interface
Default: "Other"

template (Optional)

Type: String or Boolean
Purpose: Specifies the template file for the component. If omitted, a default path is used in the current module: [Vendor]_[Module]::elements/[component-name].phtml. When set to false, the component will not use its own template - useful for child components that are rendered within their parent component's template (like the usp items in a usp_list).
Pattern: Must follow the format [Vendor]_[Module]::[template path].phtml

icon (Optional)

Type: String
Purpose: Specifies the icon file for the component
Pattern: Must follow the format [Vendor]_[Module]::[icon path].(jpg|jpeg|png|gif|webp|svg|avif)
Default: Hyva_CmsLiveviewEditor::images/components/default.svg

content, design, advanced (Optional)

Type: Object
Purpose: Groups of fields organized by their purpose
Content: Contains the main content fields of the component
Design: Contains fields related to the visual appearance
Advanced: Contains fields for more complex or technical configurations

custom_properties (Optional)

Type: Array
Purpose: Reserved to allow extending the component declaration with custom properties by developers & partners.

Component Field Declarations

Each field group (content, design, advanced) contains field declarations that define the component's editable properties. A field must be unique to all the fields in all the groups, an exception will be given in developer mode if a field with the same identifier is defined in another group.

Field Declaration Properties

includes (Optional)

Type: String or Array of Strings
Purpose: Special property to include fields from another component field declaration file
Pattern: Must follow the format [Vendor]_[Module]::[path/to/file].json

Field Identifier

Rules:
- Must be a string at least 3 characters long
- Only letters, numbers, dashes, or underscores are allowed

Field Configuration

Each field configuration includes:

type (Required)

Type: String
Purpose: Determines the kind of data the field will hold in the Hyvä CMS editor
Allowed Values: "boolean", "children", "color", "date", "html", "image", "link", "multiselect", "number", "range", "products", "richtext", "select", "searchable_select", "text", "text-align", "textarea", "variant", "custom_type"

custom_type (Optional)

Type: String
Purpose: Specifies a custom field type when type is set to "custom_type"

label (Required)

Type: String
Purpose: The label for the field in the Liveview editor form

default_value (Optional)

Purpose: The initial value assigned to the field when a new component is created

attributes (Optional)

Type: Object, string, number, integer, boolean, null, or array
Common Properties:
- minlength (string)
- maxlength (string)
- placeholder (string)
- required (boolean)
- comment (string)
Purpose: Sets HTML input attributes (placeholder, validation rules, etc.) for compatible field types

options (Optional)

Type: Array or String
Purpose: Configures available choices for fields that support selection
Allowed Values:

Array of Choice Objects: Each object contains label and value properties

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

Source Model String: A fully qualified PHP class name (with escaped backslashes) that implements OptionSourceInterface, optionally followed by ::methodName
```
"options": "Vendor\\Module\\Model\\Source\\Options"
```

config (Optional)

Type: Object
Purpose: Configuration settings that define component behavior and relationships
Properties:
accepts (array): For children fields, specifies allowed child components
```
"config": {
  "accepts": ["button", "icon", "heading"]
}
```

custom_properties (Optional)

Type: Array
Purpose: Allows extending individual field declarations with custom properties

Examples

See below and the Hyva_CmsBase module for more examples of components.

{
  "button": {
    "label": "Button",
    "category": "Example",
    "template": "Vendor_MyModule::elements/button.phtml",
    "icon": "Vendor_MyModule::images/components/button.svg",
    "content": {
      "text": {
        "type": "text",
        "label": "Button Text",
        "default_value": "Click me",
        "attributes": {
          "required": true,
          "placeholder": "Enter button text"
        }
      },
      "link": {
        "type": "link",
        "label": "Button Link"
      }
    },
    "design": {
      "includes": "Hyva_CmsBase::etc/hyva_cms/default_design.json",
      "alignment": {
        "type": "text-align",
        "label": "Alignment"
      }
    },
    "advanced": {
      "includes": "Hyva_CmsBase::etc/hyva_cms/default_advanced.json"
    }
  }
}