Skip to content

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

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 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", "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 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"
    }
  }
}