---
url: https://docs.youcan.shop/themes/config/settings_schema.md
---
# `settings_schema.json`

`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.

```json
[
  {
    "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.

```json
[
  {
    "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](/themes/settings/input_settings) that capture a value, and [display settings](/themes/settings/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`:

```liquid
{% 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 `name`s, setting `label`s, `content`, and option labels can be `t:` keys that resolve against the theme's [schema locale files](/themes/locales/schema-locale-files), which keeps the editor UI translatable.