How Shopify Schema Works

Schema is the bridge between code and merchants

Shopify section schema is JSON inside {% schema %} tags at the bottom of section.liquid files. It tells Shopify what merchants can edit—headings, images, links, colors, collection pickers—and how repeatable rows behave as blocks. Without schema, sections are frozen templates. With schema, merchants customize storefronts without deployments.

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, refine visually in Schema Generator, and study patterns in Schema Guide. Read Section Schema Explained for a complementary walkthrough.