Shopify JSON templates: how page layouts are assembled

A JSON template is a small file that says which sections a page renders and in what order. That's all it does, and it's the mechanism behind everything merchants like about Online Store 2.0 — because it means page layout is data a merchant edits, not code a developer edits.

What one looks like

``json { "sections": { "main": { "type": "main-product" }, "trust": { "type": "icon-row", "settings": { "heading": "Why buy from us" }, "blocks": { "b1": { "type": "icon", "settings": { "title": "Free returns" } }, "b2": { "type": "icon", "settings": { "title": "2-year warranty" } } }, "block_order": ["b1", "b2"] }, "related": { "type": "related-products" } }, "order": ["main", "trust", "related"] } ``

Three things to notice:

• order is the render order. The keys in sections are arbitrary identifiers.
• Settings live here, not in the section file. The section defines what settings exist; the template holds the chosen values.
• Blocks have both a map and an order, for the same reason.

When a merchant drags a section in the theme editor, they're rewriting this file. Which is the important consequence: this file is merchant data, not developer code.

Overwriting them wipes configuration

Push a JSON template from your local repository and you replace whatever the merchant arranged. Every section they added, every setting they tuned, gone — and there's no undo in the theme editor for that.

So on an existing store, either pull their templates before pushing, or exclude templates from the push:

``bash shopify theme push --theme 123456789 --ignore templates/*.json --ignore config/settings_data.json ``

This is the single most common way a developer damages a live store without touching a line of Liquid, and it's why the CLI workflow exists. The CLI workflow covers the safe routine.

Alternate templates

The genuinely useful feature. Alongside product.json you can create product.bundle.json, product.made-to-order.json, and so on. A merchant then assigns a template to individual products from the admin.

This is the right answer whenever a subset of products needs a different layout. The wrong answer — extremely common — is one template with conditional logic:

``liquid {% if product.type == 'Bundle' %} … {% else %} … {% endif %} ``

That works, and then someone adds a third type, and the template becomes unreadable. Alternate templates keep each layout separate, let the merchant control assignment, and don't require a developer when the rules change.

The same applies to collections (collection.lookbook.json) and pages (page.contact.json).

Which templates can be JSON

Most of them: index, product, collection, list-collections, page, blog, article, search, password, gift card. Cart and 404 can be Liquid or JSON depending on the theme.

Customer account templates and anything genuinely not merchant-configurable can stay Liquid. There's no benefit in making a page JSON if nobody will ever rearrange it — and there's a small cost, because every JSON template is another file a merchant can accidentally reset.

main- sections

By convention, the section that renders the page's primary content is named main-product, main-collection, main-article and so on. It's a convention rather than a rule, but following it means other developers and app blocks find what they expect.

The main- section is usually the one you should not let a merchant delete. There's no schema flag for that; the practical protection is a preset that includes it and a note in the handover documentation.

Section groups are the same idea

Header and footer areas use the same JSON structure in files under sections/, which is what lets merchants add sections to the header. Covered in sections and blocks.

A JSON template is thirty lines of configuration that represents an afternoon of a merchant's work. Treat it like their data, because it is.