Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 61 ยท Layouts, Templates and Sections

JSON Templates and Online Store 2.0

Learn how Shopify JSON templates work: sections and order, blocks, settings, alternate templates with suffixes, customer templates, Liquid templates and the limits that apply.

Before 2016 a product page was one big Liquid file that a developer edited and a merchant could not. Online Store 2.0 changed the deal. A template is now a small JSON file that says "this page is made of these sections, in this order, with these settings", and the section files hold the Liquid. The theme editor reads and writes the JSON, so merchants can add, remove and reorder sections on every page, not just the home page. As a theme developer you build the sections; the merchant assembles the pages.

This lesson covers the structure of a JSON template, how sections, blocks and order fit together, how alternate templates work, which templates must still be Liquid, and the limits you should know. The shape is described in read-only code, and an editor-run stand-in resolves a template into sections so you can watch the pieces come together.

What this lesson targets: Online Store 2.0 and current Shopify themes. JSON templates are read by Shopify, which does not run here; the editors are JavaScript stand-ins that mimic how a template is resolved, not Shopify's code. Treat numeric limits as the values at the time of writing and check the current documentation before relying on them.

What a JSON template looks like

A template is a file named after the page type, for example templates/product.json:

JSON
{
  "sections": {
    "main": {
      "type": "main-product",
      "blocks": {
        "title": { "type": "title" },
        "price": { "type": "price" },
        "buy": { "type": "buy-buttons", "settings": { "show_dynamic_checkout": true } }
      },
      "block_order": ["title", "price", "buy"],
      "settings": { "gallery_layout": "stacked" }
    },
    "related": {
      "type": "product-recommendations",
      "settings": { "heading": "You may also like" }
    }
  },
  "order": ["main", "related"]
}

There are only a few moving parts:

  • sections is an object. Each key (main, related) is the id of one section instance on this page. Each value says which section file to use (type, which is the file name in sections/ without .liquid) and holds the merchant's settings.
  • order lists the keys in the order they appear on the page. A key in sections that is not in order is not shown.
  • blocks (inside a section) works the same way: an object of block instances keyed by id, with block_order giving their order.
  • settings hold the values the merchant chose for the settings defined in the section's schema. Anything missing falls back to the schema default.

The type says which code; the key says which instance. You can have two rich-text sections on one page, with keys intro and outro, and they use the same file with different settings.

flowchart TD
  T["templates/product.json"] --> S["sections"]
  T --> O["order: main, related"]
  S --> M["main<br/>type: main-product"]
  S --> R["related<br/>type: product-recommendations"]
  M --> B["blocks + block_order<br/>title, price, buy"]
  M --> ST["settings"]
  M -. "type points to" .-> F["sections/main-product.liquid"]

A template names instances; each instance points at a section file by its type.

Files written by the theme editor start with a comment block warning that they are auto-generated. JSON templates are one of the places where Shopify tolerates comments in JSON, but do not add your own and do not expect a standard JSON parser to read these files unchanged.

Why this matters: the merchant owns the file

When a merchant adds a section in the theme editor and saves, Shopify rewrites the JSON template in the live theme. That is useful, and it is also why developer tooling cares about these files: your Git copy of templates/product.json and the merchant's copy can drift apart (Version Control and Team Workflows). Design so that you rarely need to ship JSON templates with merchant content in them.

The main section and app blocks

By convention the primary content of a template lives in a section called main, for example main-product for the product page. Templates should have at least one section that accepts app blocks (blocks of type @app), because that is how apps place their widgets on a page (App Blocks and App Embeds). A product template with no app-block-capable section cannot host app blocks.

Template types and file names

Every page type has a template name. These are the common ones:

Template Used for
index The home page
product A product
collection and list-collections One collection, and the list of all collections
page A page created in the admin
blog and article A blog index and a post
cart The cart page
search Search results
404 Not found
password The storefront password page
gift_card.liquid The gift card page (Liquid only)
customers/* Account pages: login, register, account, order, addresses, reset_password, activate_account

Templates can be .json or .liquid. Two cannot be JSON: gift_card.liquid and robots.txt.liquid, because they must contain Liquid logic. There are also metaobject templates under templates/metaobject/ for pages generated from custom data (Metaobjects in Themes).

Liquid templates versus JSON templates

A .liquid template is the pre-2.0 style: it contains Liquid and HTML, and can pull in sections only with the static {% section 'name' %} tag, which merchants cannot move or remove. It still works, and some pages (the ones listed above) require it. But for anything a merchant should be able to customize, use JSON. Do not keep both product.json and product.liquid; keep one source of truth.

JSON templates cannot contain Liquid. All logic belongs in sections, blocks and snippets, which is a good constraint: it keeps templates declarative.

Alternate templates with suffixes

A store often needs two kinds of product page: the default, and a special one for, say, gift boxes. You create an alternate template by adding a suffix to the file name: templates/product.gift-box.json. In the admin, the merchant opens a product, chooses "Theme template" and selects product.gift-box. Collections, pages, blog posts and articles work the same way. The suffix is available in Liquid as template.suffix, which you can use as a CSS hook, and the ?view=gift-box URL parameter is the traditional way to preview an alternate template.

Alternate templates can reuse every section; the difference is just a different list, order and settings. That makes them cheap, so use them for real differences in structure, not to change a heading.

Customer templates

Under classic customer accounts the pages for login, registration, order history and addresses live in templates/customers/. They are JSON or Liquid templates like any other. With Shopify's newer customer accounts, those pages are hosted by Shopify and not themeable with these files, so check which kind a store uses before you spend time on them (Customer Accounts).

Limits

Shopify limits what one template can hold. At the time of writing a JSON template can reference up to 25 sections, and each section can hold up to 50 blocks. A section's schema can also lower its own limits with limit and max_blocks. If a merchant hits a ceiling, adding another instance in the editor simply fails, so choose the schema limits on purpose.

Stand-in 1: resolving a template

The editor below does what Shopify does when a request arrives, in miniature. It takes a template and a registry of section files, validates the template, merges schema defaults into the merchant's settings, and renders the sections in order. The "section files" here are JavaScript functions standing in for Liquid.

JS Resolve a JSON template to sections

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in 2: what the theme editor does to the file

The theme editor feels like a page builder, but underneath it edits this JSON. Adding a section appends a new instance with a generated id and puts the id into order; dragging changes order; deleting removes both entries. The second editor performs those three operations on a template and prints the result. Real section ids look like random strings; here a counter keeps the output predictable.

JS The editor is a JSON editor

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practical advice

  • Ship templates that are useful on their own: sensible default sections and settings, so a new store looks good with zero setup.
  • Keep the JSON small. Put structure in the section files (with blocks and presets) and let the template only choose.
  • Never put secrets or unique store data into a template; it is a merchant-editable file.
  • Prefer a new alternate template over a conditional inside a section when the page structure really differs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In a JSON template, what is the difference between a section's key and its type?

    The key (for example intro) identifies one instance in this template; the type (for example rich-text) selects sections/rich-text.liquid. Two instances can share a type.
  2. 2. A section appears in the sections object but not in the order array. What happens?

    order controls which sections are shown and in which sequence.
  3. 3. Which of these templates cannot be a JSON template?

    gift_card.liquid and robots.txt.liquid must stay Liquid because they contain logic. Most other templates can be JSON.
  4. 4. How does a merchant use product.gift-box.json for one product?

    The suffix creates an alternate template that the merchant can assign per product, collection, page, blog or article.

Summary

  • A JSON template lists section instances (sections), their sequence (order), their blocks (blocks and block_order) and the merchant's settings.
  • A section's key identifies the instance; its type points to a file in sections/.
  • JSON templates hold no Liquid. gift_card.liquid and robots.txt.liquid must remain Liquid.
  • Alternate templates use a suffix (product.gift-box.json) and are assigned in the admin.
  • Customer templates live in templates/customers/ for classic accounts.
  • The theme editor writes the JSON, so merchant edits and your Git copy can diverge. Limits (25 sections per template and 50 blocks per section at the time of writing) apply.

Next lesson: Building a Section.