Schema files

The theme editor reads a JSON schema that defines display settings for merchants in the theme editor.

Introduction

Schema files are represenations of your theme's settings. They are required to:

Build the settings form in the Theme Editor.

Define the keys (ids) that will allow you to reference the theme settings in your templates.

The schema files are split into two types, section schema files, and layout schema files.

Note: in the old theme system, the schema used to be part of the template.twig file, now it is a separate json file.

Sections

Each section.jinja is required to have a corresponding section.schema.json file in the same directory.

Structure

Field	Type	Description
name	object {ar,en}	Section title shown to the merchant (Arabic/English).
template	string	Path to the section’s Jinja template (e.g., "sections/image_slider.jinja").
settings	array	List of inputs the merchant can change (see Input Settings).
icon	text	Optional reference to an icon at the section parent level only. Use Remixicon class names without the `ri-` prefix (e.g., `box-3-line`, `image-add-line`). See Remixicon for available icons. Note: `icon` should only be defined at the parent section level, not within individual settings objects.

Example

This is an example of what a section schema /sections/image_slider.schema.json file would look like:

{
  "name": {
    "ar": "شرائح الصور",
    "en": "Image Slider"
  },
  "settings": [
    {
      "default": true,
      "id": "hide_dots",
      "label": {
        "ar": "إخفاء النقاط",
        "en": "Hide dots"
      },
      "type": "checkbox"
    }
  ],
  "template": "sections/image_slider.jinja"
}

Layout, Header, Footer

These core jinja templates require a schema file each to represent the settings form in the theme editor. Therefore it is required you the following in your theme root directory:

layout.schema.json

header.schema.json

footer.schema.json

Structure

Field	Type	Description
name	object {ar,en}	Section title shown to the merchant (Arabic/English).
groups	array	List of objects that represent each group of settings. The structure of a group is almost identical to the schema of an individual section, but each group requires an id.
icon	text	Optional reference to an icon at the group parent level only. Use Remixicon class names without the `ri-` prefix (e.g., `box-3-line`, `image-add-line`). See Remixicon for available icons. Note: `icon` should only be defined at the parent group level, not within individual settings objects.

Example:

{
  "groups": [
    {
      "icon": "box-3-line",
      "id": "header",
      "name": {
        "ar": "رأس الصفحة",
        "en": "Header"
      },
      "settings": [
        {
          "id": "logo",
          "info": {
            "ar": "ارفع صورة بحجم 750 * 750 ",
            "en": "This is an info text sample here"
          },
          "label": {
            "ar": "الشعار",
            "en": "Logo"
          },
          "type": "image"
        }
      ]
    }
  ],
  "icon": "layout-grid-line",
  "name": {
    "ar": "اعلى الصفحة",
    "en": "Header"
  }
}

Note: Each group will appear as a fieldset in the theme editor. You do not need to explicitly specify fieldset for these groups.

You can also view a live example in the Soft Theme Vitrin Repository.

Mapping schema to keys

The settings object inside every template is a flattend version of your schema file. For example the following shorthand schema:

{
  "icon": "fa fa-square",
  "name": {
    "ar": "اعلى الصفحة",
    "en": "Header"
  },
  "groups": [
    {
      "id": "header",
       ...
      "settings": [
        {
          "id": "logo",
             ...
          }
        }
      ]
    }
  ]
}

Where the value of "logo" can be accessed as settings.header_logo in your jinja file templates.

The exception to this rule is any list settings. If a setting is inside a list, it will be treated as a list of objects that can be accessed like this in jinja:

{% for image in safeget(settings, "images", []) %}

It is good to use safeget to handle cases where a variable could be null. You can add a default value as the third paremeter of the safeget global function.

Icon Usage

The icon field in schema files accepts Remixicon class names without the ri- prefix. Icons should only be defined at the parent level of section.

How it looks:

Where to use:

Sections: Add icon at the root level of the section schema (alongside name, template, settings)

How to use:

Visit Remixicon to browse available icons

Copy the icon name (e.g., box-3-line, image-add-line, layout-grid-line)

Use the name directly in your schema's parent icon field — do NOT include the ri- prefix

Examples:

Section with icon:

{
  "icon": "image-add-line",
  "name": {
    "ar": "شرائح الصور",
    "en": "Image Slider"
  },
  "settings": [
    {
      "id": "hide_dots",
      "label": { "ar": "إخفاء النقاط", "en": "Hide dots" },
      "type": "checkbox"
    }
  ],
  "template": "sections/image_slider.jinja"
}

The system automatically prepends ri- when rendering the icon in the theme editor.

Section Preview Images

Theme developers can upload desktop and mobile preview images for each section. These images are displayed in the Theme Editor when merchants browse sections to add, and beside each existing section in the sidebar.

How it looks:

Naming Convention

Based on the section file name (e.g., slider.jinja):

View	File Name
Desktop	`slider`
Mobile	`slider_mobile`

Supported formats: png, jpg, jpeg

File Location

Place preview images in the same directory as your section template:

sections/
├── slider.jinja
├── slider.png               # Desktop preview
├── slider_mobile.png        # Mobile preview
├── testimonials.jinja
├── testimonials.jpg         # Desktop preview
├── testimonials_mobile.jpg  # Mobile preview
└── ...

Behavior

Preview images are optional: Sections work without them, but providing images improves the merchant experience.

Responsive display: The displayed preview image switches based on the frame selected in the top bar (desktop or mobile).

Fallback: If a mobile preview image is not provided, the desktop image is shown in mobile mode.

Example

For a section template featured-products.jinja:

sections/
├── featured-products.jinja
├── featured-products.png         # Shown when desktop frame is selected
└── featured-products_mobile.png  # Shown when mobile frame is selected

Introduction#

Sections#

Layout, Header, Footer#

Mapping schema to keys#

Icon Usage#

Section Preview Images#

Naming Convention#

File Location#

Behavior#

Example#

Introduction

Sections

Layout, Header, Footer

Mapping schema to keys

Icon Usage

Section Preview Images

Naming Convention

File Location

Behavior

Example