Theme Settings: settings_schema.json Deep Dive

The config/settings_schema.json file defines Theme settings in the Shopify admin—controls that apply store-wide, not per section. It is an array of setting group objects, each with name, settings array, and optional theme_support_level or role metadata. Unlike section schema, this file has no Liquid wrapper; it is pure JSON committed to version control.

Merchants access these groups under Online Store > Themes > Customize > Theme settings. Typical groups include Colors, Typography, Layout, Buttons, and Cart behavior. Each setting id becomes a global Liquid variable via settings.id_name, available in every section and snippet. Theme-wide CSS variables often derive from these settings in theme.liquid: --color-primary: {{ settings.color_primary }};

Treat settings_schema as your design token layer. Define color schemes (background, text, accent, border), font pickers for heading and body, scale ranges for border radius and spacing, and checkbox toggles for animations or sticky header. Sections reference tokens instead of hardcoded hex values so rebrandings require zero code deploys.

Shopify's color_scheme_group setting type (where supported) maps to CSS custom properties generated by Shopify for compatible themes. Even without built-in scheme groups, teams implement token maps in Liquid snippets that output CSS variables from settings. ADSPOC-style production themes centralize typography scales: settings.type_size_base multiplied by ratios in {% stylesheet %} blocks. The payoff is merchant-safe theming and fewer one-off section color pickers duplicating global palette logic.

Theme settings support the same type catalog as sections: text, textarea, richtext, select, radio, checkbox, range, number, color, color_background, image_picker, font_picker, url, link_list, collection, product, blog, page, and informational header/paragraph types. Font pickers integrate with Shopify's font library and load faces via {{ settings.type_header_font | font_face }}.

Use headers and paragraphs liberally to document intent—merchants without developer support rely on these labels. Avoid dozens of flat settings; group into logical panels. Conditional visible_if works here too, hiding advanced controls unless Enable custom CSS is checked. Keep ids stable across releases; renaming ids breaks existing merchant values in settings_data.json and requires migration scripts or default resets.

config/settings_data.json stores current theme setting values and JSON template compositions—the serialized output of merchant customization. It contains a current object with global settings key-value pairs and nested content_for_index, content_for_product, etc., mapping template names to ordered section instances with settings and blocks.

When merchants customize, Shopify writes to settings_data.json on the theme. In Git workflows, pulling live theme data merges merchant changes with developer Liquid updates—a common conflict surface. Teams often gitignore settings_data.json for developer themes while keeping settings_schema.json tracked, or use separate development themes and promote via CLI. Presets in settings_data.json under presets key store starter configurations merchants can restore.

Adding a new theme setting requires updating settings_schema.json with a default value, referencing it in Liquid/CSS, and documenting it for merchants. Removing settings orphans values in settings_data.json harmlessly but clutters data. Renaming requires a one-time Liquid fallback: {% assign primary = settings.color_primary | default: settings.old_color_primary %}.

Use theme role settings and theme_support_level to mark features for Shopify's theme store requirements. Test customization round-trips: change settings in editor, publish, verify rendered CSS variables and section inheritance. Pair settings_schema with locales for translated labels where Theme settings support translation keys. Global settings are the spine of professional themes; sections are limbs. ADSPOC-trained developers schema global tokens first, then build sections that consume them—never the reverse.