schema.json/Theme Editor Metadata

Enabling Theme Editor

To provide merchants with Theme Editor support for your theme’s settings, you must declare those settings in the theme’s <theme‑name>/schema.json file. You must also include those settings in your theme’s config.json file, templates, and Sass/CSS files. The basic division of labor is this:

• schema.json is an array of objects, declaring which theme settings are editable in Theme Editor. These objects also declare all possible values to display in Theme Editor’s GUI.
• config.json assigns (and updates) a default value for each of the editable settings.
• Each schema.json entry has an id element that maps it to its corresponding config.json entry. The id value identifies the relevant config.json key name.
• For front-matter properties to be editable, your theme’s Handlebars template must call certain Handlebars helpers to transform the config.json entries into JavaScript values.
• For fonts to be editable, a Sass stylesheet must call certain custom Sass functions to transform the config.json font entries into CSS values.
• For styles to be editable, a Sass stylesheet must call certain custom Handlebars helpers to transform the config.json entries into CSS values.

As users select options within the Theme Editor UI (and save their selections), Stencil will automatically rewrite config.json to record new defaults for the theme.

File Management Requirements

See Stencil’s default Cornerstone theme for examples that fulfill all of the above requirements. However, remember these hard requirements:

• For any theme setting (such as a Sass variable or a front-matter value) to be merchant-customizable, that setting – and its possible values – must be present in schema.json. You must manually provide these declarations, according to the structure described here.

• Also, each key that you create in schema.json must have a corresponding config.json key whose name matches its id value. This config.json key sets the default value (even if that is simply an empty string). A schema.json setting without an id-matched config.json key will not appear to users in the Theme Editor GUI.

Best Practices

Please follow these guidelines to head off errors upon theme upload, and to avoid possible loss of customizations made via the Theme Editor GUI at runtime:

• Single-Instance Restriction per Storefront: We strongly recommend opening only one instance of Theme Editor, at a time, against each storefront. This is because there is currently no synchronization mechanism to reconcile configuration changes made by multiple Theme Editor instances. So schema.json will record the last changes made by any instance – but changes saved earlier by other instances might be lost.

• Single-Storefront Restriction per Editor: In the current release, users can have only one storefront at a time open in Theme Editor. (A workaround is to open an “Incognito”/private-browsing window on an additional storefront, to bypass the cookie that imposes this restriction.)

• File Name, Location, and Structure: Your theme’s schema.json file must be named schema.json, must reside in the root of your <theme-name> subdirectory (e.g.: /cornerstone/schema.json), and must be valid JSON.

• File Size: The maximum allowable size for a theme’s schema.json file is 64 KB. Exceeding this limit will trigger an error upon uploading the theme to BigCommerce. (Other than this size constraint, there is no limit on the number of keys and values that you can place in a theme’s schema.json.)

How .json Entries Govern Theme Editor’s UI

Your entries in the schema.json and config.json files directly shape users’ options in Theme Editor:

• Theme Variations always appear at the top of the Theme Editor panel. These variations are defined only in config.json, and their definition order in that file governs their display order in Theme Editor.
• Merchants must select one variation to edit, at a time, in Theme Editor. The selections that they make in the remainder of Theme Editor’s UI will apply to only that selected variation.
• Theme Editor’s remaining sequence of top-level (Section) headings corresponds directly to the sequence of top-level (Section) objects that you declare in schema.json

The options displayed within these expandable Section headings correspond directly to the keys/values that you nest within schema.json's corresponding Section objects.

In all, the structure that you give your theme’s config.json and schema.json files directly governs the UI that Theme Editor exposes to merchants. So these files provide your UI design tools.

Theme Editor Data Types

Theme editor supports these data types:

• color
• font
• select [drop-down list]
• checkbox
• imageDimension
• text

Within schema.json, each object’s data type is declared in a statement like the one highlighted here:

 {
        "type": "color",
        "label": "Text Color",
        "id": "body-font-color"
      },

Types versus “heading” Labels

Within schema.json, you will also see "type": "heading" statements like this one – highlighted earlier in the same object used for the above example:

 {
    "name": "Colors",
    "settings": [
      {
        "type": "heading",
        "content": "General"
      },
      {
        "type": "color",
        "label": "Text Color",
        "id": "body-font-color"
      },

These "type": "heading" statements do not reference data types. Rather, they declare display captions for the Theme Editor UI’s subcategories – the middle level nested within the Section headings, but outside the individual options from which merchants can select. (Those inner options are designated by "label": <label-text> statements.)

Theme Editor/schema.json Data Structure

The schema.json nesting structure that you just saw maps directly to the Theme Editor UI displayed to merchants: Below the Variations Section (whose data are imported from config.json), the order and nesting of options in Theme Editor’s UI directly matches the order and nesting of your schema.json entries.