JSON templates

JSON templates allow you to control the look and feel of different pages of the online store using sections.

JSON templates are data files that store a list of sections to be rendered, and their associated settings. Merchants can add, remove, and reorder these sections using the theme editor. When a page is rendered with a JSON template, the sections are rendered in the order specified by the content_for_pages attribute. There's no markup between the sections.

The filename must be a valid theme template type. For example, a product template can be named product.liquid.

Template structure

JSON templates must be valid JSON files. The root should be an object with the following attributes:

Attribute

Type

Required

Description

content_for_page

Array

Yes

An array of section IDs, listed in the order that they should be rendered. The IDs must exist in the sections object. Duplicates are not allowed.

sections

Object

Yes

An object that uses section IDs as keys, and section data as values. This attribute needs to contain at least one section.

Duplicate IDs within the template are not allowed.

The format of the section data is the same as section data in settings_data.json. To learn more, refer to Section data.

📘

Tip

Section files must define presets in their schema to support being added to JSON templates using the theme editor. Section files without presets should be included in the JSON file manually, and can't be removed using the theme editor.

Section data

The sections attribute of JSON templates holds the data for the sections to be rendered by the template. These can be either theme sections. You can't share section data across JSON theme templates, so each section must have an ID that's unique within the template.

The following table outlines the format of section data:

Value

Type

Required

Description

<SectionID>

String

A unique ID for the section. Accepts only alphanumeric characters.

<SectionType>

String

Yes

The filename of the section file to render, without the extension.

<BlockType>

String

Yes

The type of block to render, as defined in the schema of the section file.

<SettingID>

String

The ID of a setting as defined in the schema of the section or the block.

(multiple)

A valid value for the setting.

For example:

sections: {
  <SectionID>: {
    "type": <SectionType>,
    "settings": { 
      <SettingID>: <SettingValue 
    },
    "blocks": [
      {
        "type": <BlockType>,
        "settings": {
          <SettingID>: <SettingValue>
        }
      }
    ]
  }
}

For example, the following template renders the product.liquid and product-recommendations.liquid section files on product pages:

{
 "content_for_page": [1621646423258],
 "sections": {
   "1621646423258": {
     "type": "product",
     "settings": {
       "layout_on": false,
       "author_on": false,
       "date_on": true,
       "show_vendor": true
     },
     "version": "1",
     "card_name": "product",
     "customer_card_extra": 6,
     "customer_card_name": "product",
     "is_new": true,
     "blocks": []
   }
 }
}

🚧

Caution

Any sections that are included in a template, must exist in the theme. If they don't, then this will result in an error.


Did this page help you?