JSON Templates vs Liquid Templates in Shopify

In classic Shopify themes, templates like product.liquid contained the entire page markup—hero, tabs, related products, reviews—all hard-coded in one file. Merchants could not rearrange blocks without a developer. Online Store 2.0 introduced JSON templates (product.json, collection.json, index.json) that declare an ordered list of sections. Each section is a self-contained unit with its own Liquid markup, {% schema %} settings, and optional JavaScript. The theme editor reads JSON templates and renders a drag-and-drop UI for sections and blocks.

Liquid templates still exist and remain valid for pages that should not be composed in the theme editor—checkout.liquid (Plus), gift_card.liquid, and some legacy layouts. For product, collection, page, blog, article, cart, search, and 404 pages, JSON is the default in modern themes. A JSON template does not contain HTML; it contains section IDs, types, settings, and block order. Shopify hydrates each section's .liquid file at render time and merges settings from the JSON with defaults from the section schema.

A minimal product.json looks like this conceptually: a sections object mapping unique keys to { type, settings, blocks, block_order }, plus an order array listing section keys top to bottom. The type value matches the filename in sections/ without .liquid—type: "main-product" loads sections/main-product.liquid. Section keys must be unique within the template; ADSPOC uses descriptive keys like main-product, product-recommendations, and recently-viewed rather than generic section-1.

Settings in JSON override schema defaults. blocks nest inside sections that declare block types in schema—think collapsible tabs, icon rows, or trust badges on a PDP. block_order controls block sequence within a section. When merchants customize in the theme editor, Shopify writes changes back to JSON in the live theme—or to a settings_data.json backup for shared section instances. Developers seed JSON templates in Git with opinionated defaults so new theme installs look finished on first preview, not empty skeletons.

Use JSON templates when merchants need layout control—homepage storytelling, PDP modules, collection banners, landing pages built from reusable sections. JSON maximizes theme editor value and reduces post-launch developer tickets for 'move this below that' requests. Use Liquid templates when the page must be fixed, minimal, or outside the section system: password.liquid, gift_card.liquid, or a highly custom page where editor flexibility would break compliance or performance budgets.

Hybrid approaches exist. layout/theme.liquid remains Liquid and wraps all JSON-driven pages. Sections can be rendered statically from Liquid via {% section 'announcement-bar' %} in the layout, while template JSON adds page-specific sections below. ADSPOC puts global elements (header, footer, cart drawer) in layout or section groups and keeps JSON templates focused on page content stacks—typically 3–6 sections per PDP, not fifteen, to protect Lighthouse scores and merchant sanity.

Alternate templates let one resource type render with different section stacks. Create product.gift.json and assign it to products in Admin; the URL stays /products/handle but Shopify loads the gift template instead of product.json. Suffix naming is strict: product.{suffix}.json maps to template suffix {suffix} in the product admin dropdown. Same pattern for collection.brand.json, page.landing.json, and article.feature.json.

Alternate templates power lookbooks, B2B product pages with MOQ tables, gift-card-style PDPs, and campaign landing collections without conditional spaghetti in a single section file. Each alternate template can reuse the same section types with different settings—{% render %} and shared snippets keep DRY markup across templates. ADSPOC documents every alternate template in the theme README with screenshots and assignment rules so merchandising teams know which products get which experience.

Section groups (header-group.json, footer-group.json) bundle sections that appear together across templates—sticky header, announcement bar, mega menu. They live in sections/ as JSON group files and load via {% sections 'header-group' %} in layout. Theme blocks (Shopify's newer block architecture on supported sections) let blocks nest across section boundaries on the homepage; adoption is growing but not every section supports them yet—check schema block type compatibility before planning cross-section drag-and-drop.

Migrating classic Liquid templates to JSON: extract each visual region into a section file with schema, register the section type in a new JSON template, move hard-coded settings to schema defaults, and delete the old .liquid template once parity is verified. Test alternate templates, empty states, and mobile order. ADSPOC migration projects always ship a before/after theme editor map so clients understand which sections replaced which legacy includes—reducing training friction and preventing duplicate sections left over from half-finished migrations.