Template JSON reference

A template describes one page as data. It names section types and their settings — never markup, never a component, never a schema. The files your agent edits:

File	What it is
`templates/<name>.json`	One page template: `index`, `product`, `collection`, `page`, `404`, and alternates such as `product.alternate-1`
`sections/<group>-group.json`	A section group — the shared header or footer rendered around every page
`config/settings_data.json`	Theme-wide settings (colours, fonts) and static sections

All three are template_data files: every write is parsed and validated as a Builder2 document, and a file that fails is refused with INVALID_JSON or INVALID_TEMPLATE rather than written.

The document

templates/index.json

{
  "version": 2,
  "sections": {
    "hero-1": {
      "type": "hero",
      "settings": { "headline": "Clean energy, no crash" },
      "blocks": {
        "g1": {
          "type": "group",
          "settings": {},
          "blocks": { "t1": { "type": "text", "settings": { "body": "Launching this week" } } },
          "block_order": ["t1"]
        }
      },
      "block_order": ["g1"],
      "disabled": false
    }
  },
  "order": ["hero-1"]
}

Field	Rule
`version`	Required integer. The current version is `2`.
`sections`	A map from section id to a section instance. Ids are opaque strings — hyphens are fine.
`order`	Array of section ids. Authoritative for render order. A section in `sections` but not in `order` is kept and never rendered. An id in `order` with no entry in `sections` is skipped.
`type`	A registered section or block type: a platform type such as `hero`, or one of your custom sections such as `custom-ingredient-grid`.
`settings`	Values keyed by the schema’s setting `id`.
`blocks` / `block_order`	Same shape as `sections` / `order`, and recursive: a block may contain blocks.
`disabled`	`true` hides a section or block without losing its settings.

An unknown section type is skipped at render, never an error that breaks the page, so a store keeps serving pages if a type is removed. Theme check reports it so you notice. The manifest’s section_types and block_types list every type available in the theme — platform and custom — with its settings, allowed blocks, max_blocks and placement rules. Read it before writing a template rather than guessing setting ids.

Limits

Limit	Value	Note
Sections per template	25	Per document. Section groups have their own budget.
Blocks per section	50	A section’s schema may lower this with `max_blocks`.
Blocks per template	1,250	Usually the one that binds first.
Block nesting depth	8

The manifest returns these as limits, together with the write limits: 50 files per write and 2 MiB per file.

Section groups

The header and footer are section groups, not sections copied into every template. A group file has the same sections / order shape as a template, and is rendered around every page: header group, then the page’s template, then the footer group. Where a section may go is decided by its schema, on two independent axes:

Axis	Reads	When the schema says nothing
Templates	`enabled_on.templates` / `disabled_on.templates`	allowed on every template
Groups	`enabled_on.groups` / `disabled_on.groups`	not allowed in any group

So a section meant for both a page and the footer must name both. Placing a section where its schema does not allow it is a builder2-template error.

Alternate templates

An alternate is named <template>.<suffix>: product.alternate-1, collection.wide. Which products or collections use it is stored on the product or collection, never in the template. If a product names an alternate that does not exist, the base template (product) is used.

Things to avoid

Hand-writing ids that collide. Section and block ids must be unique within their map.
Copying the header into a template. Edit the header group instead.
Writing data/. It is generated from your catalog on every publish; writes are refused with IGNORED_PATH.
Sample content. Theme check refuses lorem ipsum, “Your Store”, “Coming soon”, “Product name”, href="#" and empty images. A value you do not have should be left out, not faked.

Build with your agent

Theme reference

Template JSON reference

The document

Limits

Section groups

Alternate templates

Things to avoid

​The document

​Limits

​Section groups

​Alternate templates

​Things to avoid

The document

Limits

Section groups

Alternate templates

Things to avoid