1. Home
2. Themes
3. Key Concepts
4. Config
5. settings_schema.json

settings_schema.json

Last updated Oct 8, 2026 View as Markdown

config/settings_schema.json defines the theme's global settings. It's a JSON array of setting groups, each rendered as a titled section in the theme editor.

[
  {
    "name": "t:settings_schema.typography.label",
    "settings": [
      { "type": "header", "content": "t:settings_schema.typography.font_family" },
      {
        "type": "select",
        "id": "font_family",
        "label": "t:settings_schema.typography.font_family_label",
        "options": [
          { "value": "DM+Sans", "label": "DM Sans" },
          { "value": "Roboto", "label": "Roboto" }
        ],
        "default": "DM+Sans"
      }
    ]
  },
  {
    "name": "t:settings_schema.seo.label",
    "settings": [
      { "type": "image_picker", "id": "favicon", "label": "t:settings_schema.seo.favicon_image" },
      { "type": "text", "id": "keywords", "label": "t:settings_schema.seo.keywords" }
    ]
  }
]

Theme info

The first entry of the array can declare the theme's information. It is not a setting group, and the theme editor does not show it.

[
  {
    "name": "theme_info",
    "theme_name": "Origins",
    "theme_author": "YouCan",
    "theme_version": "1.0.0",
    "theme_documentation_url": "https://docs.youcan.shop",
    "theme_support_url": "https://docs.youcan.shop"
  },
  {
    "name": "t:settings_schema.typography.label",
    "settings": []
  }
]

Property	Type	Required	Description
name	string	Yes	Always theme_info.
theme_name	string	Yes	The theme's name, up to 32 characters.
theme_author	string	Yes	The theme's author, up to 32 characters.
theme_version	string	Yes	The theme's version, in semantic versioning (X.Y.Z).
theme_documentation_url	string	Yes	A URL to the theme's documentation.
theme_support_url	string	One of the two	A URL where sellers can get support.
theme_support_email	string	One of the two	An email address where sellers can get support.

• Give exactly one of theme_support_url and theme_support_email.
• theme_info must be the first entry, and appear only once. No other properties are allowed.
• When the entry is present, it is the source of the theme's name, author, version, and links. youcan theme init writes it for you, and saving the file with youcan theme dev updates the theme's information.
• A file with an invalid theme_info is rejected when you save it, with an error for each field.

Group object

Property	Type	Required	Description
name	string	Yes	The group's title in the theme editor. Usually a t: locale key. label is accepted as a deprecated alias.
settings	array	Yes	The setting definitions in this group.

Setting entries

Each entry in a group's settings array is a setting definition, using the same types as section settings: input settings that capture a value, and display settings such as header and paragraph that only add context.

• Every entry needs a type.
• Every input setting needs an id, and that id must be unique across the whole file.

Reading values in Liquid

Theme settings are exposed on the global settings object, keyed by id:

{% if settings.keywords != blank %}
  <meta name="keywords" content="{{ settings.keywords }}">
{% endif %}

If the seller hasn't set a value, the setting's default from the schema is used. Settings with no value and no default resolve to blank.

Locale keys

Group names, setting labels, content, and option labels can be t: keys that resolve against the theme's schema locale files, which keeps the editor UI translatable.