shopify-schema-design

name	Shopify Schema Design
description	Best practices for creating comprehensive section schemas with all setting types

Shopify Schema Design

Schema Structure

The {% schema %} tag defines how a section appears in the theme editor:

{
  "name": "Section Name",
  "tag": "section",
  "class": "section-class",
  "limit": 1,
  "settings": [...],
  "blocks": [...],
  "presets": [...]
}

Setting Types

Text Input

{
  "type": "text",
  "id": "heading",
  "label": "Heading",
  "default": "Default text",
  "info": "Helpful description",
  "placeholder": "Enter text here"
}

Textarea

{
  "type": "textarea",
  "id": "description",
  "label": "Description",
  "default": "Default description"
}

Rich Text

{
  "type": "richtext",
  "id": "content",
  "label": "Content",
  "default": "<p>Default rich text content</p>"
}

Number / Range

{
  "type": "range",
  "id": "padding",
  "label": "Padding",
  "min": 0,
  "max": 100,
  "step": 4,
  "unit": "px",
  "default": 40,
  "info": "Section padding in pixels"
}

Checkbox

{
  "type": "checkbox",
  "id": "show_vendor",
  "label": "Show Product Vendor",
  "default": true,
  "info": "Display vendor name on product cards"
}

Select / Dropdown

{
  "type": "select",
  "id": "layout",
  "label": "Layout Style",
  "options": [
    {
      "value": "grid",
      "label": "Grid"
    },
    {
      "value": "carousel",
      "label": "Carousel"
    },
    {
      "value": "list",
      "label": "List"
    }
  ],
  "default": "grid",
  "info": "Choose how products are displayed"
}

Radio Buttons

{
  "type": "radio",
  "id": "alignment",
  "label": "Text Alignment",
  "options": [
    {
      "value": "left",
      "label": "Left"
    },
    {
      "value": "center",
      "label": "Center"
    },
    {
      "value": "right",
      "label": "Right"
    }
  ],
  "default": "center"
}

Color Picker

{
  "type": "color",
  "id": "bg_color",
  "label": "Background Color",
  "default": "#ffffff",
  "info": "Section background color"
}

Color Background

{
  "type": "color_background",
  "id": "background_gradient",
  "label": "Background Gradient",
  "info": "Supports solid colors and gradients"
}

Image Picker

{
  "type": "image_picker",
  "id": "image",
  "label": "Image",
  "info": "Recommended size: 1600 x 900 px"
}

Font Picker

{
  "type": "font_picker",
  "id": "heading_font",
  "label": "Heading Font",
  "default": "assistant_n4",
  "info": "Choose font for headings"
}

Collection Picker

{
  "type": "collection",
  "id": "collection",
  "label": "Collection"
}

Product Picker

{
  "type": "product",
  "id": "featured_product",
  "label": "Featured Product"
}

Product List

{
  "type": "product_list",
  "id": "products",
  "label": "Products",
  "limit": 12,
  "info": "Select up to 12 products"
}

Collection List

{
  "type": "collection_list",
  "id": "collections",
  "label": "Collections",
  "limit": 8
}

Blog Picker

{
  "type": "blog",
  "id": "blog",
  "label": "Blog"
}

Article Picker

{
  "type": "article",
  "id": "article",
  "label": "Article"
}

Page Picker

{
  "type": "page",
  "id": "page",
  "label": "Page"
}

Link / URL

{
  "type": "url",
  "id": "button_link",
  "label": "Button Link",
  "info": "Link to internal page or external URL"
}

Video URL

{
  "type": "video_url",
  "id": "video",
  "label": "Video URL",
  "accept": ["youtube", "vimeo"],
  "info": "Supports YouTube and Vimeo"
}

HTML

{
  "type": "html",
  "id": "custom_html",
  "label": "Custom HTML",
  "info": "Add custom HTML code"
}

Liquid

{
  "type": "liquid",
  "id": "custom_liquid",
  "label": "Custom Liquid",
  "info": "Add custom Liquid code"
}

Organizational Elements

Header

{
  "type": "header",
  "content": "Section Heading"
}

Paragraph

{
  "type": "paragraph",
  "content": "Helpful information or instructions for merchants."
}

Complete Schema Example

{% schema %}
{
  "name": "Product Grid",
  "tag": "section",
  "class": "product-grid-section",
  "settings": [
    {
      "type": "header",
      "content": "Content"
    },
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "Featured Products"
    },
    {
      "type": "richtext",
      "id": "description",
      "label": "Description"
    },
    {
      "type": "collection",
      "id": "collection",
      "label": "Collection"
    },
    {
      "type": "range",
      "id": "products_count",
      "label": "Number of Products",
      "min": 2,
      "max": 12,
      "step": 1,
      "default": 4
    },
    {
      "type": "header",
      "content": "Layout"
    },
    {
      "type": "select",
      "id": "layout",
      "label": "Layout Style",
      "options": [
        {
          "value": "grid",
          "label": "Grid"
        },
        {
          "value": "carousel",
          "label": "Carousel"
        }
      ],
      "default": "grid"
    },
    {
      "type": "select",
      "id": "columns_desktop",
      "label": "Desktop Columns",
      "options": [
        {
          "value": "2",
          "label": "2"
        },
        {
          "value": "3",
          "label": "3"
        },
        {
          "value": "4",
          "label": "4"
        }
      ],
      "default": "4"
    },
    {
      "type": "select",
      "id": "columns_mobile",
      "label": "Mobile Columns",
      "options": [
        {
          "value": "1",
          "label": "1"
        },
        {
          "value": "2",
          "label": "2"
        }
      ],
      "default": "1"
    },
    {
      "type": "header",
      "content": "Product Card"
    },
    {
      "type": "checkbox",
      "id": "show_vendor",
      "label": "Show Product Vendor",
      "default": false
    },
    {
      "type": "checkbox",
      "id": "show_quick_view",
      "label": "Enable Quick View",
      "default": true
    },
    {
      "type": "header",
      "content": "Colors"
    },
    {
      "type": "color",
      "id": "bg_color",
      "label": "Background Color",
      "default": "#ffffff"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Text Color",
      "default": "#000000"
    },
    {
      "type": "header",
      "content": "Spacing"
    },
    {
      "type": "range",
      "id": "padding_top",
      "label": "Top Spacing",
      "min": 0,
      "max": 100,
      "step": 4,
      "unit": "px",
      "default": 40
    },
    {
      "type": "range",
      "id": "padding_bottom",
      "label": "Bottom Spacing",
      "min": 0,
      "max": 100,
      "step": 4,
      "unit": "px",
      "default": 40
    }
  ],
  "blocks": [
    {
      "type": "featured_product",
      "name": "Featured Product",
      "settings": [
        {
          "type": "product",
          "id": "product",
          "label": "Product"
        }
      ]
    }
  ],
  "presets": [
    {
      "name": "Product Grid",
      "settings": {
        "heading": "Featured Products",
        "products_count": 4
      }
    }
  ]
}
{% endschema %}

Blocks Configuration

Basic Blocks

{
  "blocks": [
    {
      "type": "heading",
      "name": "Heading",
      "settings": [
        {
          "type": "text",
          "id": "text",
          "label": "Text",
          "default": "Heading"
        }
      ]
    },
    {
      "type": "paragraph",
      "name": "Paragraph",
      "settings": [
        {
          "type": "richtext",
          "id": "content",
          "label": "Content"
        }
      ]
    }
  ],
  "max_blocks": 10
}

Accept All Theme Blocks

{
  "blocks": [
    {
      "type": "@theme"
    }
  ]
}

Accept App Blocks

{
  "blocks": [
    {
      "type": "@app"
    }
  ]
}

Presets

Basic Preset

{
  "presets": [
    {
      "name": "Hero Banner"
    }
  ]
}

Preset with Default Settings

{
  "presets": [
    {
      "name": "Product Grid",
      "settings": {
        "heading": "Featured Products",
        "products_count": 4,
        "columns_desktop": "4"
      }
    }
  ]
}

Preset with Blocks

{
  "presets": [
    {
      "name": "Testimonials",
      "blocks": [
        {
          "type": "testimonial"
        },
        {
          "type": "testimonial"
        },
        {
          "type": "testimonial"
        }
      ]
    }
  ]
}

Best Practices

1. Group Related Settings with Headers

{
  "settings": [
    {
      "type": "header",
      "content": "Content Settings"
    },
    {
      "type": "text",
      "id": "heading",
      "label": "Heading"
    },
    {
      "type": "header",
      "content": "Layout Settings"
    },
    {
      "type": "select",
      "id": "columns",
      "label": "Columns"
    }
  ]
}

2. Always Provide Defaults

{
  "type": "text",
  "id": "heading",
  "label": "Heading",
  "default": "Default Heading"  ← Always provide!
}

3. Add Info Text for Complex Settings

{
  "type": "range",
  "id": "products_count",
  "label": "Number of Products",
  "min": 2,
  "max": 12,
  "default": 4,
  "info": "Maximum number of products to display from the selected collection"
}

4. Use Appropriate Input Types

• Text/numbers → text, textarea, number, range
• True/false → checkbox
• Multiple options → select, radio
• Resources → collection, product, image_picker
• Colors → color, color_background

5. Set Reasonable Limits

{
  "type": "range",
  "id": "padding",
  "min": 0,        ← Minimum value
  "max": 100,      ← Maximum value
  "step": 4,       ← Increment
  "default": 40    ← Sensible default
}

6. Include Presets for Quick Setup

{
  "presets": [
    {
      "name": "Section Name",
      "settings": {
        "heading": "Default Heading",
        "show_feature": true
      },
      "blocks": [
        {
          "type": "block_type"
        }
      ]
    }
  ]
}

Create schemas that make section customization intuitive and efficient for merchants.