Shopify Settings Schema: A Developer's Guide

Shopify settings schema is how themes expose customization options to merchants in the theme editor. Understanding how it works is essential for building themes, customizing sections, and extending functionality without modifying code directly. This guide covers the two main contexts where settings schema appears — settings_schema.json for global theme settings, and the {% schema %} tag for section and block settings.

settings_schema.json

The settings_schema.json file lives in your theme's /config folder and controls the Theme settings panel in the Shopify theme editor. Any settings defined here are global — they apply across the entire theme and are accessible in Liquid via the settings object.

The file is a JSON array of objects, where each object represents a group (rendered as a section in the Theme settings sidebar) and contains an array of individual settings:

[
  {
    "name": "Colors",
    "settings": [
      {
        "type": "color",
        "id": "color_background",
        "label": "Background color",
        "default": "#ffffff"
      }
    ]
  }
]

After saving changes to this file, refresh the theme editor to see the new settings appear at the bottom of the Theme settings panel.

The {% schema %} Tag in Section Files

Section-level and block-level settings are defined using the {% schema %} tag inside .liquid section files. The tag accepts a JSON object that defines the section's name, settings, blocks, presets, and constraints. It must appear once per section file and is not rendered in the storefront output.

{% schema %}
{
  "name": "Featured collection",
  "settings": [
    {
      "type": "collection",
      "id": "collection",
      "label": "Collection"
    }
  ],
  "presets": [
    {
      "name": "Featured collection"
    }
  ]
}
{% endschema %}

Settings defined here are accessed in Liquid via section.settings.collection (or block.settings.id for block-level settings).

Input Setting Types

Both settings_schema.json and section schemas support the same set of input setting types. These fall into two categories: basic input types and specialized Shopify object types.

Basic input types include text (single-line), textarea (multi-line), number, checkbox, radio, select, and range. These map directly to standard HTML input elements and are the building blocks for most theme settings.

Specialized types let merchants pick Shopify resources directly from the editor: color for a color picker, image_picker for an image, collection for a collection, product for a product, blog, page, link_list, font_picker, and video_url among others. These return a Shopify object or resource ID that you can use in Liquid to render dynamic content.

There is also an html type for arbitrary HTML input and a richtext type for a basic rich text editor. The complete list of supported types is documented in Shopify's input settings reference.

Blocks

Blocks are repeatable, orderable units within a section. Each block type is defined in the blocks array of the section schema and has its own settings. Merchants can add, remove, and reorder blocks in the theme editor without touching code.

"blocks": [
  {
    "type": "testimonial",
    "name": "Testimonial",
    "settings": [
      {
        "type": "text",
        "id": "author",
        "label": "Author name"
      },
      {
        "type": "textarea",
        "id": "quote",
        "label": "Quote"
      }
    ]
  }
]

Block settings are accessed in Liquid when iterating: {% for block in section.blocks %}{{ block.settings.author }}{% endfor %}.

App blocks allow third-party apps to inject content into sections. To support app blocks in a section, include { "type": "@app" } in the blocks array. This enables merchants to add app block content from the theme editor without code changes.

Presets

Presets define the default state of a section when a merchant adds it from the theme editor. A section without a preset won't appear in the "Add section" menu on JSON template pages. At minimum, a preset needs a name:

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

The blocks array in a preset populates the section with default block instances when it's first added, so merchants start with useful content rather than an empty section.

Limiting Section Usage

The enabled_on and disabled_on schema keys control which templates and section groups a section can be used on. For example, to restrict a section to product pages only:

"enabled_on": {
  "templates": ["product"]
}

The limit key controls how many times a section can be added to a single template. Setting "limit": 1 prevents merchants from adding a section more than once, which is useful for sections like headers or announcement bars.

Localization

Settings schema supports localization through schema locale files in /locales. Rather than hardcoding label and default text values in the schema JSON, you can reference translation keys using the t: prefix. This keeps your settings labels translatable without duplicating schema definitions for each language. See Shopify's schema locale files documentation for the structure.

Accessing Settings in Liquid

Global theme settings (from settings_schema.json) are accessed via the settings object: {{ settings.color_background }}. Section settings are accessed via section.settings.id, and block settings via block.settings.id inside a blocks loop. Settings with no value return an empty string in Liquid.

For deeper reference, see Shopify's settings_schema.json documentation and the section schema reference.