Settings Schema

The settings_schema.json file defines all configurable settings for your theme. These settings appear in the Basker CMS admin panel, allowing editors to customize the theme without modifying code.

File Location

The settings schema must be placed at:

your-theme/
└── config/
    └── settings_schema.json

File Structure

The settings schema is a JSON array containing:

A theme metadata object (first item)
One or more setting group objects

[
  {
    "name": "theme_settings",
    "theme_name": "My Theme",
    "theme_version": "1.0.0",
    "theme_author": "Your Name"
  },
  {
    "name": "header",
    "type": "group",
    "fields": [...]
  },
  {
    "name": "footer",
    "type": "group",
    "fields": [...]
  }
]

Theme Metadata

The first object in the array defines theme metadata. This information is displayed in the CMS when managing themes.

Property	Type	Description
`name`	`string`	Must be `"theme_settings"`
`theme_name`	`string`	Display name of the theme
`theme_version`	`string`	Semantic version (e.g., `"1.0.0"`)
`theme_author`	`string`	Theme author name
`theme_documentation_url`	`string`	URL to theme documentation
`theme_support_url`	`string`	URL for support inquiries

Example:

{
  "name": "theme_settings",
  "theme_name": "Starter Theme",
  "theme_version": "1.0.0",
  "theme_author": "Your Company",
  "theme_documentation_url": "https://docs.example.com",
  "theme_support_url": "https://support.example.com"
}

Setting Groups

Settings are organized into groups. Each group appears as a collapsible section in the admin panel.

{
  "name": "header",
  "label": "Header Settings",
  "type": "group",
  "fields": [
    {
      "type": "text",
      "name": "logoText",
      "label": "Logo Text"
    }
  ]
}

Property	Type	Required	Description
`name`	`string`	Yes	Unique identifier for the group
`label`	`string`	No	Display label (defaults to `name`)
`type`	`string`	Yes	Must be `"group"`
`fields`	`array`	Yes	Array of field definitions

Accessing Settings in Templates

Settings are available via the global settings object in Liquid templates:

{# Access by group and field name #}
{{ settings.header.logoText }}
{{ settings.footer.background }}
{{ settings.social.facebook_link }}

{# Use in conditionals #}
{% if settings.header.showAnnouncement %}
  <div class="announcement">
    {{ settings.header.announcementText }}
  </div>
{% endif %}

{# Loop through arrays #}
{% for link in settings.footer_links %}
  <a href="{{ link.href }}">{{ link.text }}</a>
{% endfor %}

Complete Example

Here’s a comprehensive settings schema example:

[
  {
    "name": "theme_settings",
    "theme_name": "Starter Theme",
    "theme_version": "1.0.0",
    "theme_author": "Your Company"
  },
  {
    "name": "header",
    "label": "Header",
    "type": "group",
    "fields": [
      {
        "type": "upload",
        "name": "logo",
        "label": "Logo",
        "relationTo": "media"
      },
      {
        "type": "text",
        "name": "donateLink",
        "label": "Donate Button URL",
        "default": "/donate"
      },
      {
        "type": "checkbox",
        "name": "showAnnouncement",
        "label": "Show Announcement Bar",
        "default": false
      },
      {
        "type": "text",
        "name": "announcementText",
        "label": "Announcement Text"
      },
      {
        "type": "color",
        "name": "background",
        "label": "Background Color",
        "default": "#FFFFFF"
      }
    ]
  },
  {
    "name": "footer",
    "label": "Footer",
    "type": "group",
    "fields": [
      {
        "type": "color",
        "name": "background",
        "label": "Background Color",
        "default": "#1a1a1a"
      },
      {
        "type": "color",
        "name": "foreground",
        "label": "Text Color",
        "default": "#ffffff"
      },
      {
        "type": "richtext",
        "name": "copyrightText",
        "label": "Copyright Text"
      }
    ]
  },
  {
    "name": "footer_links",
    "label": "Footer Links",
    "type": "array",
    "fields": [
      {
        "type": "text",
        "name": "text",
        "label": "Link Text"
      },
      {
        "type": "text",
        "name": "href",
        "label": "Link URL"
      }
    ]
  },
  {
    "name": "social",
    "label": "Social Media",
    "type": "group",
    "fields": [
      {
        "type": "text",
        "name": "facebook_link",
        "label": "Facebook URL"
      },
      {
        "type": "text",
        "name": "instagram_link",
        "label": "Instagram URL"
      },
      {
        "type": "text",
        "name": "twitter_link",
        "label": "X (Twitter) URL"
      },
      {
        "type": "text",
        "name": "youtube_link",
        "label": "YouTube URL"
      },
      {
        "type": "text",
        "name": "linkedin_link",
        "label": "LinkedIn URL"
      }
    ]
  },
  {
    "name": "global",
    "label": "Global Settings",
    "type": "group",
    "fields": [
      {
        "type": "upload",
        "name": "fallbackImage",
        "label": "Fallback Image",
        "relationTo": "media"
      },
      {
        "type": "text",
        "name": "googleAnalyticsId",
        "label": "Google Analytics ID"
      }
    ]
  }
]

Field Types Reference

Basic Fields

Type	Description	Default Value
`text`	Single-line text input	`""`
`textarea`	Multi-line text input	`""`
`number`	Numeric input	`0`
`checkbox`	Boolean toggle	`false`
`select`	Dropdown selection	First option
`radio`	Radio button group	First option
`color`	Color picker	`"#000000"`

Rich Content Fields

Type	Description
`richtext`	Rich text editor with formatting
`code`	Code editor with syntax highlighting
`json`	JSON editor

Relationship Fields

Type	Description	Requires
`upload`	Media file selection	`relationTo`
`relationship`	Link to other content	`relationTo`

Structure Fields

Type	Description
`group`	Groups related fields
`array`	Repeatable field set

Field Attributes

All fields support these standard attributes:

Attribute	Type	Required	Description
`type`	`string`	Yes	The field type
`name`	`string`	Yes	Unique field identifier
`label`	`string`	No	Display label in admin
`default`	`any`	No	Default value

Relationship Fields

For upload and relationship types:

Attribute	Type	Required	Description
`relationTo`	`string`	Yes	Collection to relate to (e.g., `"media"`, `"pages"`)
`hasMany`	`boolean`	No	Allow multiple selections

{
  "type": "relationship",
  "name": "featuredPosts",
  "label": "Featured Posts",
  "relationTo": "posts",
  "hasMany": true
}

Select and Radio Fields

For select and radio types:

Attribute	Type	Required	Description
`options`	`array`	Yes	Array of option objects

{
  "type": "select",
  "name": "alignment",
  "label": "Text Alignment",
  "options": [
    { "label": "Left", "value": "left" },
    { "label": "Center", "value": "center" },
    { "label": "Right", "value": "right" }
  ],
  "default": "left"
}

Array Fields

Arrays allow editors to add multiple entries of a repeated structure:

{
  "name": "navigation_items",
  "label": "Navigation Items",
  "type": "array",
  "fields": [
    {
      "type": "text",
      "name": "label",
      "label": "Label"
    },
    {
      "type": "text",
      "name": "url",
      "label": "URL"
    },
    {
      "type": "checkbox",
      "name": "openInNewTab",
      "label": "Open in New Tab",
      "default": false
    }
  ]
}

Accessing array data in templates:

<nav>
  {% for item in settings.navigation_items %}
    <a href="{{ item.url }}"
       {% if item.openInNewTab %}target="_blank" rel="noopener"{% endif %}>
      {{ item.label }}
    </a>
  {% endfor %}
</nav>

Nested Groups

Groups can contain other groups for hierarchical organization:

{
  "name": "colors",
  "label": "Color Settings",
  "type": "group",
  "fields": [
    {
      "name": "primary",
      "type": "group",
      "label": "Primary Colors",
      "fields": [
        { "type": "color", "name": "background", "label": "Background" },
        { "type": "color", "name": "text", "label": "Text" }
      ]
    },
    {
      "name": "secondary",
      "type": "group",
      "label": "Secondary Colors",
      "fields": [
        { "type": "color", "name": "background", "label": "Background" },
        { "type": "color", "name": "text", "label": "Text" }
      ]
    }
  ]
}

Accessing nested settings:

<style>
  :root {
    --primary-bg: {{ settings.colors.primary.background }};
    --primary-text: {{ settings.colors.primary.text }};
    --secondary-bg: {{ settings.colors.secondary.background }};
    --secondary-text: {{ settings.colors.secondary.text }};
  }
</style>

Best Practices

Use descriptive names - Field names should be clear and consistent (e.g., donateLink not link1)
Provide defaults - Always set sensible default values so themes work out of the box
Group logically - Organize related settings together (header, footer, social, etc.)
Use appropriate types - Choose field types that match the expected input (use color for colors, not text)
Keep it minimal - Only expose settings that editors actually need to customize
Document your settings - Include theme_documentation_url to link to your theme docs