Shopify Section Schema: Settings, Blocks, and Presets

Every Online Store 2.0 section ends with a {% schema %} ... {% endschema %} block containing valid JSON. Shopify parses this at upload time to build the theme editor UI. Required fields include name (editor label) and settings (array of setting objects). Optional top-level keys include tag, class, limit, max_blocks, blocks, presets, default, enabled_on, disabled_on, and locales.

Schema JSON is not Liquid; you cannot interpolate Liquid variables inside it. Dynamic defaults use Liquid outside schema or rely on setting types like product picker defaults. Invalid schema JSON fails theme check and blocks upload. Keep schema readable: group related settings with header and paragraph types, use consistent id naming (snake_case), and document non-obvious settings with info type fields.

Shopify provides a rich setting type vocabulary. Common inputs: text, textarea, richtext, html, number, range, checkbox, select, radio, color, color_background, image_picker, video, url, font_picker, collection, product, product_list, blog, page, link_list, and metaobject. Each type renders a native editor control and stores typed values accessible in Liquid as section.settings.setting_id.

Structural types organize the panel: header inserts a label divider; paragraph shows helper copy. Conditional visibility uses visible_if (JSON Logic expressions referencing other setting ids) to hide irrelevant fields—for example, show video_url only when media_type equals video. In Liquid, access settings with section.settings.heading and block settings with block.settings.text. Always guard optional settings: {% if section.settings.image != blank %} prevents broken img tags.

The blocks array declares block types merchants can add inside the section. Each block object needs type (machine name), name (editor label), and settings array. Optional limit per block type restricts duplicates. Render blocks by looping section.blocks and switching on block.type:

Use {{ block.shopify_attributes }} on the outer element for theme editor integration. Block settings follow the same type system as section settings. For theme blocks shared across sections, reference Shopify's theme blocks specification where block types are defined once and imported by type string. max_blocks on the section caps total blocks, preventing performance issues on runaway merchant configurations.

presets is an array of prefilled section configurations shown when merchants click Add section. Each preset includes name, optional category for grouping in the picker, settings object with id-value pairs, and blocks array with type, settings, and optional block id. Merchants can add the same section multiple times with different presets—for example, Hero with video vs Hero with image.

If you omit presets, Shopify generates a generic entry from section name and default settings. Invest time in presets for complex sections: product tabs, multicolumn features, and FAQ accordions. Presets are marketing for your section architecture—they show merchants what is possible without reading documentation.

enabled_on restricts where a section can be added. Accepts templates array (product, collection, index, etc.), groups array (header, footer, custom.overlay), and optional json_template_types. disabled_on excludes specific contexts. Use these to keep the section picker relevant: do not offer cart-only sections on article templates.

The tag property wraps section output in a semantic HTML element; class adds a CSS class on the section wrapper Shopify generates. Combine tag: section with class: spacing-style for predictable layout hooks. For CSS, prefer {% stylesheet %} inside the section file so styles travel with the section. Schema-driven development scales teams: designers map to setting types, developers implement Liquid against stable ids, and merchants configure without deploys.