Shopify schema guide for section developers

What section schema does

Section schema is the JSON contract between your Liquid markup and the Shopify theme editor. It declares which parts of a section merchants can edit—headings, images, links, colors, collection pickers—and how repeatable rows behave as blocks. Without schema, a section is frozen HTML. With thoughtful schema, the same section powers dozens of storefront layouts.

Schema lives inside {% schema %} tags at the bottom of section.liquid files. Shopify validates it on save and renders form fields in the editor sidebar. The /liquid-schema-generator and /converter both output schema aligned with Online Store 2.0 rules.

Schema structure overview

• name — display name in the theme editor and Add section list
• tag — optional semantic wrapper (section, header, footer)
• class — optional CSS class on the section wrapper
• settings — array of section-level setting objects
• blocks — array of block type definitions
• max_blocks — limit repeatable rows
• presets — default configurations surfaced in Add section
• default — fallback values for settings

{% schema %}
{
  "name": "Feature grid",
  "tag": "section",
  "settings": [],
  "blocks": [
    {
      "type": "feature",
      "name": "Feature",
      "settings": []
    }
  ],
  "max_blocks": 12,
  "presets": [{ "name": "Feature grid", "blocks": [{ "type": "feature" }] }]
}
{% endschema %}

Section settings deep dive

Section settings apply to the whole section—module heading, background color, collection picker, padding controls. Each setting needs a unique id, a type, and a merchant-facing label. Optional help_text and info fields reduce support tickets.

Common setting types

• text — single-line strings for headings and labels
• richtext — multi-paragraph copy with basic formatting
• image_picker — uploads tied to image_url and image_tag filters
• url — link picker for CTAs and external URLs
• collection / product — resource pickers for merchandising sections
• range — numeric sliders for padding, font size, product limits
• checkbox — boolean toggles for show/hide features
• select — enumerated options mapped to CSS modifier classes
• color — hex color picker for backgrounds and text

{
  "type": "range",
  "id": "padding_top",
  "min": 0,
  "max": 100,
  "step": 4,
  "unit": "px",
  "label": "Top padding",
  "default": 36
}

Blocks in schema

Blocks define repeatable content types—FAQ items, slides, feature cards. Each block type has its own settings array. In Liquid you loop {% for block in section.blocks %} and read block.settings. Merchants add, remove, and reorder blocks in the editor.

Use max_blocks to prevent performance issues. Name block types clearly—faq_item not block_1. See /dynamic-shopify-blocks-guide for slider, FAQ, and tab block patterns.

Presets and defaults

Presets make sections discoverable. A preset needs a name and can seed settings values and block rows. Without presets, merchants must configure sections from scratch every time.

"presets": [{
  "name": "FAQ — Shipping",
  "blocks": [
    { "type": "faq_item", "settings": { "question": "How long is shipping?" } },
    { "type": "faq_item", "settings": { "question": "Do you ship internationally?" } }
  ]
}]

Schema best practices

• Keep setting counts manageable—under 15 section settings when possible.
• Use stable ids; renaming breaks existing merchant data.
• Group related settings with header and paragraph types for editor UX.
• Match setting types to content—never use text for images.
• Validate JSON before deploy; trailing commas break schema parsing.
• Test on Dawn first; OS 2.0 conventions transfer to most themes.

From schema to production sections

Start from HTML in /converter, refine schema in /liquid-schema-generator, and cross-reference patterns in /shopify-liquid-cheatsheet. For component-specific schema—heroes, banners, product grids—see /convert-hero-section-html-to-liquid and related component guides.