JSON templates

A JSON template is a .json file in the theme's templates directory that describes which sections render on a page, in what order, and with what settings. Unlike a Liquid template, its contents are data: the theme editor reads and writes this file as sellers add, remove, reorder, and configure sections.

Location

└── theme
    ├── layout
    ├── templates
    │   ├── index.json
    │   ├── product.json
    │   ├── cart.json
    │   ...
    ...

Structure

{
  "label": "Search",
  "layout": "theme",
  "sections": {
    "main-search": {
      "type": "main-search",
      "settings": {}
    }
  },
  "order": ["main-search"]
}

At minimum a template needs a sections object and an order array. Everything else is optional.

Top-level properties

Property	Type	Required	Description
sections	object	Yes	Maps a section ID to a section object. A template can hold between 1 and 25 sections.
order	array	Yes	Section IDs listed in render order. Every ID must be a key in sections; duplicates aren't allowed. Sections omitted from order aren't rendered.
label	string	No	The template's display name in the theme editor. Max 255 characters.
layout	string	No	Filename (without extension) of the layout the template renders into. Defaults to theme. Set to null to render without a layout.
wrapper	string	No	HTML element that wraps the template's sections. One of div, section, or main.

Section object

Each entry in sections is keyed by a section ID (letters, numbers, -, and _, up to 40 characters) and holds:

Property	Type	Required	Description
type	string	Yes	The section filename (without extension) in the sections directory, e.g. "slideshow" renders sections/slideshow.liquid.
settings	object	No	Values for the section's settings, keyed by the setting id defined in the section's {% schema %}.
blocks	object	No	Maps a block ID to a block object. Up to 25 blocks per section.
order	array	No	Block IDs listed in render order. Every ID must be a key in blocks; duplicates aren't allowed. Required whenever blocks is present. Blocks missing from order aren't rendered.
disabled	boolean	No	When true, the section is kept in the file and stays configurable in the editor but isn't rendered. Defaults to false.

"slideshow": {
  "type": "slideshow",
  "settings": {},
  "blocks": {
    "slide_1": {
      "type": "slide_item",
      "settings": {
        "slide_heading": "Explore a fantastic world",
        "first_button_label": "Shop Now"
      }
    },
    "slide_2": {
      "type": "slide_item",
      "settings": { "slide_heading": "New arrivals" }
    }
  },
  "order": ["slide_1", "slide_2"]
}

Block object

Each entry in a section's blocks is keyed by a block ID (same rules as section IDs) and holds:

Property	Type	Required	Description
type	string	Yes	The block type as declared in the section's schema blocks.
settings	object	No	Values for the block's settings, keyed by setting id.

Ordering and IDs

• order arrays (at both template and section level) are the source of truth for what renders and in what sequence. An entry in sections or blocks with no matching ID in the corresponding order is stored but not rendered.
• IDs only need to be unique within their scope and stable across edits. The theme editor generates values like block_65254f3c09e4c8; hand-written templates can use readable IDs like slide_1.
• A section's type can repeat across different IDs. That's how a page shows the same section more than once with different settings.

Full example

{
  "sections": {
    "slideshow": {
      "type": "slideshow",
      "settings": {},
      "blocks": {
        "slide_1": {
          "type": "slide_item",
          "settings": { "slide_heading": "Explore a fantastic world" }
        }
      },
      "order": ["slide_1"]
    },
    "featured-collection": {
      "type": "featured-collection",
      "settings": {
        "heading": "New Arrivals",
        "button_label": "View all"
      }
    },
    "faqs": {
      "type": "faqs",
      "settings": { "heading": "FAQs" },
      "disabled": true
    }
  },
  "order": ["slideshow", "featured-collection", "faqs"]
}