Shopify JSON Templates Architecture for Agencies

Multi-template client launches expose JSON architecture fast: duplicate section keys, orphaned order entries, and header groups that fight page-level sections. These agency patterns came from wholesale and DTC launches where three JSON templates had to stay consistent across twenty-seven custom sections.

Online Store 2.0 moved page structure from monolithic Liquid files into JSON templates under templates/ — index.json, product.json, collection.json, and alternates like page.landing.json. For agencies, JSON templates are the contract between developers, merchants, and Git. They define which sections appear, in what order, with which settings and blocks pre-filled. Messy template architecture causes duplicate sections, missing presets on new pages, app block slots lost on product.json merges, and deploys that overwrite merchant reordering unexpectedly. This guide is how we structure template repos, name alternates, and coordinate with Section Workflow and Presets on client work.

JSON template anatomy — what agencies own

Each template JSON has sections object keyed by instance ids — template--1234567890__hero — and order array listing those keys. Each section entry stores type matching filename in sections/, settings object, blocks object, block_order array. Agencies own initial structure and defaults; merchants own ongoing content and reordering. Version control must track intentional template changes separately from merchant drift — some teams use Shopify CLI pull before commit; others treat live editor as content CMS and only commit structural releases. Pick a policy per client and document it in README.

{
  "sections": {
    "hero": {
      "type": "hero-split",
      "settings": { "heading": "Summer collection" }
    },
    "featured": {
      "type": "featured-collection",
      "settings": { "collection": "frontpage" }
    }
  },
  "order": ["hero", "featured"]
}

Template inventory at project kickoff

Before building sections, list templates: index, product, collection, cart, search, blog, article, page, 404, password, plus alternates — page.landing-lead.json, product.bundle.json. Map each to Figma pages. Unbuilt templates should not accumulate orphan sections only on homepage. How Shopify Sections Work explains template routing when PMs ask why a section does not appear on collection pages — enabled_on restrictions.

Section instance keys: readable versus generated

Shopify editor generates opaque keys; hand-built JSON can use readable keys like hero_main if unique within template. Readable keys simplify Git diffs. After merchant edit, Shopify may rewrite keys — do not rely on key stability across long merchant sessions. Reference by type and position in order array when communicating with team.

Launch defaults versus schema presets

index.json at launch should mirror best preset content — same block counts, same headings. Presets power future Add section; index.json powers day-one homepage. Divergence confuses QA comparing homepage to blank page insert. When updating presets post-launch, remember existing index.json does not auto-update — plan content migration or accept drift.

Alternate templates without explosion

Landing campaigns get page.landing-{campaign}.json cloned from page.json base — strip nav-heavy sections, add storytelling modules. Product alternates for bundles vs standard PDP — product.bundle.json drops incompatible blocks. Cap alternates; ten landing templates nobody remembers creates editor clutter. Naming convention: page.landing-{slug}.json lowercase kebab. Document in merchant sheet which template to pick for new page.

product.json architecture and sacred blocks

main-product section block_order is revenue-critical — title, price, variant picker, buy buttons, description, @app blocks. Custom product templates duplicate at peril. Prefer block_order adjustments inside one main-product schema over multiple product.liquid files unless types truly diverge. Leave @app in blocks array for subscription and reviews apps. Test product.json after every app install near launch — apps mutate JSON. App Blocks Guide covers @app handshake.

collection.json and filtering sections

Collection templates stack collection banner, product grid, marketing sections. Filtering UI depends on Search & Discovery and theme support — do not promise custom filter JSON without API alignment. Merchandising sections below grid should use enabled_on collection templates only.

JSON templates and theme settings_data.json

Global theme settings live in config/settings_data.json — colors, typography, header behavior. Template JSON references sections; settings_data references header/footer section groups in some themes. Deploy merges can conflict. CLI pull before push on active merchant stores. Teach clients which changes live in theme settings versus page sections.

enabled_on, disabled_on, and template guards

Section schema restricts templates — FAQ section disabled_on homepage if duplicate elsewhere. JSON can still reference type if manually added — schema guard prevents editor add, not all JSON invalid cases. Validate JSON templates in CI with script checking types exist as files and enabled_on allows template name.

Multi-market and localization

Markets may duplicate templates per locale or use same template with translated settings — plan before building ten near-identical JSON files. Dynamic content via metafields reduces template duplication. Metafields Patterns for market-specific product facts.

Git workflow for agencies

Branch per client or monorepo per client — never mix client JSON in one branch. PR review checks: new section types registered on correct templates, order matches Figma narrative, no dev-only sections left on index.json, block_order arrays present when blocks exist. Merge conflicts in JSON are painful — assign template owner per release.

Merchant editor permissions and governance

Staff accounts with theme edit can reorder homepage — expected. Agencies deliver reset JSON snapshot or duplicate theme for experiments. Document Add section versus edit settings. Merchants breaking layout by deleting spacing sections is training issue; missing section file is deploy issue.

Testing JSON templates before launch

1. Open every template route in preview — index, product, collection, cart, each alternate
2. Reorder sections in editor; confirm order persists after save
3. Add section via preset on page template; confirm enabled_on rules
4. Install representative apps; verify product.json block_order intact
5. Mobile preview each template — section stack differs
6. Compare Git index.json to editor export after QA pass

Migrating vintage Liquid templates to JSON

Vintage theme.liquid layout sections do not port 1:1. Rebuild homepage as index.json section stack. Content entry hours belong in proposal. Map old includes to new section types spreadsheet. Redirects and handle changes are SEO parallel work. Run password-protected duplicate theme until JSON parity signed off.

Performance and JSON template size

Twenty sections on index.json is common; forty slows editor drag. Split storytelling to child landing templates. Lazy sections below fold still load — JSON size is not TTFB main factor, but editor UX degrades. Performance Tips for render cost per section type.

Documentation deliverable for clients

TEMPLATE_MAP.md: template name, URL example, purpose, sections included, who may edit. Screenshot theme editor template picker for page creation. Link Section Tutorial. Agencies who skip this get "which template for Black Friday landing" every quarter.

Anti-patterns in agency JSON work

• All custom sections only on index.json — landing pages re-empty
• Hand-editing app block JSON without editor export
• Duplicate section types with different instance settings and no naming doc
• product.json missing @app after theme update merge
• Deploying Git index.json over merchant holiday reorder without warning
• Orphan section files never referenced — theme bloat

Header and footer section groups in JSON themes

Dawn stores header and footer as sections in settings_data.json section groups — not in index.json. Agencies customizing header must coordinate JSON template work with section group JSON. Breaking header group JSON breaks every template. Test header/footer separately from homepage section stack during deploy review.

Password page and 404 templates

password.json and 404.json are easy to forget until launch week. Include branded sections on password template for pre-launch hype; minimal 404 with search and featured collection reduces bounce. Map in TEMPLATE_MAP.md with same rigor as index.json.

Cart and customer account templates

cart.json may include upsell sections below line items — JSON order matters for conversion. customers/account.json templates vary by theme; custom loyalty bands need enabled_on guards. Test logged-in customer templates separately — product object absent, different globals.

CLI pull, push, and merchant drift policy

Define whether live theme editor changes get pulled to Git weekly or only at quarterly releases. Merchants who reorder homepage without Git backup lose changes on agency deploy if agency overwrites JSON. Educate clients: structural changes we deploy; content changes they own — or pull before every deploy. Write policy in maintenance contract.

JSON validation script for CI

Simple Node script: parse each templates/*.json, verify sections.*.type file exists in sections/, verify order keys match sections keys, warn on unknown types. Run on PR. Catches typos hero-spli before merge. Cheap automation for agency repos with fifty templates.

// pseudo-check
for (const file of glob('templates/*.json')) {
  const json = JSON.parse(read(file));
  for (const key of json.order) {
    const type = json.sections[key].type;
    assert(fs.existsSync(`sections/${type}.liquid`));
  }
}

Landing page factory for campaign teams

Standard page.campaign.json with ordered storytelling sections — hero, social proof, offer, FAQ, newsletter. Marketing duplicates page in admin, picks template, swaps copy in editor without dev. Agency maintains template JSON defaults quarterly. Scales better than custom JSON per campaign in Git.

SEO and JSON template section order

Critical content higher in order array is not always higher in DOM — depends on section Liquid. Do not assume order equals SEO priority; use proper heading hierarchy inside sections. FAQ schema sections should not duplicate JSON-LD across multiple templates blindly — one FAQ page template owns structured data.

B2B catalog templates versus D2C

B2B clients may need collection.json variants with quick-order sections, login-gated pricing bands on index.json for approved customers only via Liquid customer checks — JSON still lists sections, Liquid gates render. Document which templates behave differently when buyer is logged in.

blog.json and article.json for content marketing clients

Editorial clients need article.json with related products section, newsletter band, and author bio blocks. JSON template order affects reader flow — CTA mid-article versus end. Map blog templates in kickoff when content team is primary user. Merchants publish articles without developer but depend on template JSON defaults for first insert.

list-collections and search templates

list-collections.json often neglected — B2B portals with many catalogs need branded collection index. search.json should include helpful empty state sections when no results — reduces bounce. Include in template inventory even when Figma did not deliver designs — use sensible presets.

Theme editor JSON versus theme ZIP deploy

shopify theme push overwrites remote JSON unless ignored in config. .shopifyignore for settings_data.json is common; template JSON usually deploys from Git. Teams ignoring templates/*.json in ignore file accidentally wipe merchant homepage on push — onboarding checklist item for new developers joining agency.

Section instance limits and Shopify platform caps

Extremely large JSON templates approach platform limits — rare but real on landing pages with forty sections. Split into multiple pages or lazy-load heavy content sections. Editor becomes sluggish before hard limits hit — treat performance as architecture signal.

Agency reusable template starter kit

We maintain internal starter repo: index.json, product.json, page.json, page.landing.json with placeholder section types and documented order. New client clones kit, renames section types as custom sections ship. Cuts day-one JSON scaffolding. Update kit when OS 2.0 platform adds template features — JSON version key in Shopify release notes.

Coordinating JSON with section development sprints

Sprint ends when sections merge and index.json updated — not when Liquid merges alone. PM acceptance includes editor walkthrough on JSON defaults. Converter produces sections; humans wire templates. Two-hour section workflow includes JSON registration minutes 80–95 for reason.

Rollback plan when JSON deploy goes wrong

Keep tagged Git release before major template restructure. Shopify admin duplicate theme before deploy. If homepage JSON corrupts, restore from Git tag or duplicate theme publish — document steps in runbook. Merchants panic when homepage white-screens; agency calm with rehearsed rollback wins trust. Test rollback on staging quarterly.

JSON templates and A/B testing tools

Third-party A/B tools may inject sections or replace template JSON on experiment cohorts — coordinate so agency Git deploy does not wipe experiment config. Document which tools client marketing installed. Template architecture includes apps that mutate JSON at runtime, not only static Git files.

Onboarding new agency developers to template repo

Day one: read TEMPLATE_MAP.md, open index.json, trace each type to sections/ file, reorder one section in editor on duplicate theme, diff JSON. Hands-on beats reading Shopify docs alone. New hire who understands JSON templates avoids breaking product.json in week two when assigned first solo task.

JSON templates are the sitemap of your theme editor — if they are chaotic, merchants get lost before CSS ever loads.

Quarterly template audit for long-term retainers

Every quarter on retainer clients: diff index.json live versus Git, list orphan sections in repo, verify product.json still has @app, remove dev sections from production templates. Prevent template entropy that makes every campaign deploy scary. Billable retainer hours with tangible hygiene deliverable.

Teaching merchants JSON limits without JSON vocabulary

Merchants do not need JSON syntax — they need rules: do not delete sections you do not recognize, duplicate page before big reorder experiments, screenshot before Black Friday edits. Translate template architecture into behavioral guardrails. Reduces emergency restore requests when someone removes main-product from product template thinking it looked duplicate.

Template architecture in client proposals

Proposal line item: JSON template setup — index, product, collection, cart, two landing alternates, TEMPLATE_MAP.md. Sets expectation that templates are deliverables, not invisible glue. Clients who understand templates ask for campaign template instead of homepage surgery. Agencies who hide template work in generic development hours underprice OS 2.0 complexity.

Versioning template JSON in release notes

Client-facing release notes mention template changes: Added page.landing-sale.json, reordered index.json hero below announcement. Merchants understand deploy impact. Silent JSON changes feel like bugs when homepage order shifts after agency push they did not know about. Transparency reduces "you broke my site" calls when change was intentional improvement.

Syncing JSON architecture with app install runbook

Every app install near launch triggers runbook step: export product.json, verify @app block present, diff block_order against Git baseline, re-run product page QA. Apps mutate JSON silently — architecture doc is worthless if process does not guard product template after third-party installs. Marketing must freeze app experiments forty-eight hours before BFCM cutover.

Handing TEMPLATE_MAP.md to client ops team

Ops teams creating landing pages need template picker guidance, not repo access. TEMPLATE_MAP.md exported to PDF with screenshots lives in client shared drive. Reduces wrong template selection that stacks sections incompatible with campaign tracking or app embeds.

Schedule thirty minutes in launch retro to review template JSON incidents — what broke, what guardrail failed, what runbook step was skipped. JSON architecture improves when retros name templates explicitly, not "the homepage issue." Treat templates as first-class repo artifacts alongside sections/. Align presets, index.json, and handoff docs. Review product.json after every app install. Name alternates predictably. JSON architecture is not glamorous — it is how agencies ship OS 2.0 without becoming permanent homepage editors. Reusable Sections plus disciplined templates let merchants launch campaigns without a retainer ticket.