The documentation you are reading pertains to a product currently under development. As it is still evolving, the features, specifications, and details provided herein are subject to change without notice. We recommend checking back regularly for the most up-to-date information.
Component Declaration JSON Schema
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: If not set, the component name will be used instead
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 tofalse
, the component will not use its own template - useful for child components that are rendered within their parent component's template (like theusp
items in ausp_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", "products", "richtext", "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
andvalue
properties -
Source Model String: A fully qualified PHP class name (with escaped backslashes) that implements OptionSourceInterface, optionally followed by ::methodName
config (Optional)
- Type: Object
- Purpose: Configuration settings that define component behavior and relationships
- Properties:
-
accepts (array): For children fields, specifies allowed child components
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"
}
}
}