The Ultimate Guide to Shopify's `schema`: Settings, Presets, and Best Practices

For any Shopify theme developer, the {% schema %} tag is the heart of the merchant experience. It’s the magic that transforms a static Liquid file into a dynamic, configurable section in the Shopify Theme Editor. A well-crafted schema empowers merchants to customize their storefront with confidence, while a poorly designed one can lead to confusion and frustration.

Mastering the schema is not just about knowing the different setting types. It’s about understanding how to structure your settings logically, how to provide clear instructions, and how to leverage advanced features like presets to create a truly intuitive user experience.

This guide will take you beyond the basics and into the best practices that separate a good theme from a great one.

The Anatomy of a Schema

At its core, a schema is a JSON object that defines the structure and settings of a section. Let’s break down the key properties:

{% schema %}
{
  "name": "My Awesome Section",
  "tag": "section",
  "class": "my-awesome-section",
  "settings": [
    // Array of setting objects
  ],
  "blocks": [
    // Array of block objects
  ],
  "presets": [
    // Array of preset objects
  ]
}
{% endschema %}

"name": The human-readable name that appears in the theme editor.
"tag": Determines the HTML tag that wraps the section (usually "section"). Use "div" for sections that shouldn’t be semantic landmarks.
"class": A CSS class that will be automatically added to the section’s wrapper element.
"settings": The array of controls that merchants will interact with.
"blocks": Defines repeatable content blocks that can be added, removed, and reordered.
"presets": The default configuration for the section when a merchant adds it for the first time.

Best Practices for Crafting Your Settings

The quality of your schema is defined by the clarity and usability of its settings.

Don’t present merchants with a flat, overwhelming list of options. Use the header type to group related settings into logical sections.

"settings": [
  {
    "type": "header",
    "content": "Typography"
  },
  {
    "type": "font_picker",
    "id": "heading_font",
    "label": "Heading font"
  },
  {
    "type": "header",
    "content": "Colors"
  },
  {
    "type": "color",
    "id": "background_color",
    "label": "Background color"
  }
]

2. Provide Clear Instructions with `info`

Never assume a merchant knows what a setting does. Use the "info" property to provide clear, concise instructions or context.

{
  "type": "image_picker",
  "id": "background_image",
  "label": "Background image",
  "info": "Recommended size: 2048x1024px. Leave blank to use a solid color."
}

3. Use `placeholder` for Context

For text-based inputs, the "placeholder" property can provide helpful examples of the expected content.

{
  "type": "text",
  "id": "heading",
  "label": "Heading",
  "placeholder": "Announce your promotion"
}

4. Choose the Right Setting Type

Shopify offers a rich variety of setting types. Choosing the most appropriate one makes the merchant’s life easier.

Use range for numerical values with a defined min/max, like font size or padding.
Use select for a predefined list of options, like alignment or style variations.
Use checkbox for simple on/off toggles.
Use richtext instead of textarea when you want to allow basic formatting like bold or italics.

The Power of Presets

The "presets" array is one of the most important parts of your schema. A preset defines the default state of a section when a merchant adds it from the “Add section” list.

A good preset should:

Look great out of the box: It should be pre-configured with sensible defaults and placeholder content so the section is immediately usable.
Demonstrate the section’s potential: Use the preset to showcase the different features and block types the section supports.

"presets": [
  {
    "name": "Image with Text",
    "settings": {
      "heading": "Showcase Your Brand",
      "background_color": "#f5f5f5"
    },
    "blocks": [
      {
        "type": "image"
      },
      {
        "type": "text",
        "settings": {
          "subheading": "Tell your story"
        }
      }
    ]
  }
]

This preset gives the section a name in the editor, sets some default values for the main settings, and even adds two blocks by default.

Final Thoughts: The Schema is Your UI

As a theme developer, the schema is the user interface you are building for your primary user: the merchant.

By investing the time to create a schema that is well-structured, clearly documented, and thoughtfully configured, you are not just making a theme that is more powerful; you are making a theme that is a joy to use. And a merchant who enjoys using your theme is a merchant who will trust it to power their business for years to come.

❓ What’s your favorite “pro-tip” for writing a clean and user-friendly schema?