Getting Started
About Stencil
Transitioning to Stencil
Installing Stencil
Authentication & Tokens
Running Stencil Locally
Advanced Installation Options
Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars and Stencil
Handlebars Helpers
Stencil Object Model
Stencil Objects

schema.json (Store Design Metadata)

Enabling Store Design

To provide merchants with Store Design support for your theme’s settings, you must declare those settings in the theme’s 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 Store Design. These objects also declare all possible values to display in Store Design’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 Store Design 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 Store Design GUI.

Best Practices

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

  • Single-Instance Restriction per Storefront: We strongly recommend opening only one instance of Store Design, at a time, against each storefront. This is because there is currently no synchronization mechanism to reconcile configuration changes made by multiple Store Design 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 Store Design. (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 Store Design’s UI

Your entries in the schema.json and config.json directly shape users’ options in Store Design:

  • Theme Variations always appear at the top of the Store Design panel. These variations are defined only in config.json, and their definition order in that file governs their display order in Store Design.
  • Merchants must select one variation to edit, at a time, in Store Design. The selections that they make in the remainder of Store Design’s UI will apply to only that selected variation.
  • Store Design’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 Store Design exposes to merchants. So these files provide your UI design tools.

Store Design Data Types

Store Design 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 Store Design 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.)

Store Design Data Structure in schema.json

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

Arbitrary UI Scope and Sequence

You are free to decide which properties of your theme to make editable in Store Design, and in which order to display them. Store Design can expose any set of properties as long as your schema.json declares them using the data types that Store Design supports.