How Shopify Schema Works

Schema is the bridge between code and merchants

{% schema %} JSON at the bottom of each section file defines sidebar fields merchants edit—settings, blocks, presets. Stable setting ids preserve merchant data across theme deploys; invalid JSON prevents the section from appearing in the editor at all.

How the theme editor reads schema

When a merchant opens the theme editor, Shopify parses each section's schema and renders form fields in the sidebar. Each setting id becomes section.settings.your_id in Liquid. Each block type becomes a template for rows merchants add, remove, and reorder.

Schema changes require theme code deploys. Merchant edits to setting values live in theme JSON—not in your schema file—so stable setting ids are critical.

Settings: section-level controls

Settings apply to the whole section—module heading, background color, collection picker, padding range. Common types: text, richtext, image_picker, url, collection, product, range, checkbox, select, color.

{
  "type": "text",
  "id": "heading",
  "label": "Heading",
  "default": "Featured collection"
}

Blocks: repeatable rows

Blocks power FAQs, sliders, feature cards, and tabs. Schema defines block types; Liquid loops section.blocks. Merchants manage rows in the editor. See Dynamic Blocks Guide and How to Build Dynamic Blocks.

Presets and discovery

Presets surface sections in the Add section panel. A preset needs a name and can seed default settings and blocks. Custom sections without presets are invisible to merchants on JSON templates.

Defaults and merchant-first UX

Default values in schema pre-fill settings on new section instances. Good defaults mean merchants see a usable layout immediately—placeholder copy, sample images, two FAQ rows—not empty fields.

Schema best practices

• Keep setting counts manageable; group with header settings.
• Use descriptive ids—heading not field_1.
• Match setting types to content; richtext for formatted body copy.
• Set max_blocks on repeatables to protect editor performance.
• Validate JSON before commit; trailing commas break parsing.

From schema theory to practice

Generate schema from HTML with HTML to Liquid Converter, then open the converter workspace, refine visually in Schema Generator, and study patterns in Schema Guide. Read Section Schema Explained for a complementary walkthrough.

Schema JSON is versioned with your theme

Deploying schema changes requires theme release. Merchant edits to setting values live in template JSON on Shopify servers—stable setting ids preserve data across deploys; renames wipe merchant content. Treat ids like database columns.

blocks, presets, and default block arrays

"presets": [{
  "name": "FAQ",
  "blocks": [
    { "type": "faq_item", "settings": { "question": "Shipping times?" } },
    { "type": "faq_item", "settings": { "question": "Returns?" } }
  ]
}]

Seed two block rows so merchants see repetition working immediately—reduces "empty section" support tickets.

Theme editor rendering pipeline

Shopify parses schema → builds sidebar fields → writes values to template JSON → hydrates section.settings and block.settings at render. If sidebar fields look wrong, fix schema—not Liquid first.

Troubleshooting

• Invalid JSON → section absent from editor
• Missing preset → cannot add section dynamically
• Wrong block type in preset → validation error on insert