schema Tag

The schema tag defines metadata, settings, and block restrictions for templates and blocks. The content is parsed during theme processing but does not render any output.

Syntax

{% schema %}
{
  "name": "identifier",
  "settings": [...],
  "blocks": [...]
}
{% endschema %}

Output

The schema tag produces no output. It’s processed during theme upload to extract configuration.

Schema Structure

For Templates

Template schemas define custom fields and allowed blocks:

{# templates/event.liquid #}

{% layout 'layouts/default.liquid' %}

{% capture content_for_layout %}
  <h1>{{ event.title }}</h1>
  {% stageblocks event %}
{% endcapture %}

{% schema %}
{
  "name": "event",
  "settings": [
    {
      "type": "upload",
      "name": "hero_image",
      "label": "Hero Image",
      "relationTo": "media"
    },
    {
      "type": "group",
      "name": "cta",
      "label": "Call to Action",
      "fields": [
        { "type": "text", "name": "text", "label": "Button Text" },
        { "type": "text", "name": "url", "label": "Button URL" }
      ]
    }
  ],
  "blocks": [
    "accordion",
    "content",
    "feature-panel",
    "image-gallery"
  ]
}
{% endschema %}

Property	Type	Description
`name`	`string`	Template identifier (should match content type)
`settings`	`array`	Custom fields available via `[content].theme`
`blocks`	`array`	Allowed block types (omit to allow all)

For Blocks

Block schemas define the block’s configuration:

{# blocks/hero.liquid #}

<section id="{{ block.id }}" class="hero">
  <h1>{{ block.heading }}</h1>
  <p>{{ block.subheading }}</p>
</section>

{% schema %}
{
  "name": "hero",
  "singular": "Hero",
  "plural": "Heroes",
  "label": "Hero Block",
  "settings": [
    {
      "type": "text",
      "name": "heading",
      "label": "Heading"
    },
    {
      "type": "text",
      "name": "subheading",
      "label": "Subheading"
    }
  ]
}
{% endschema %}

Property	Type	Description
`name`	`string`	Block type identifier
`singular`	`string`	Singular display name
`plural`	`string`	Plural display name
`label`	`string`	Label shown in admin UI
`settings`	`array`	Field definitions for the block

Accessing Schema-Defined Fields

Template Settings

Template settings are available via the theme property:

{# In templates/page.liquid #}
{% if page.theme.show_sidebar %}
  <aside>{{ page.theme.sidebar_content_html }}</aside>
{% endif %}

Block Settings

Block settings are available directly on the block object:

{# In blocks/hero.liquid #}
<h1>{{ block.heading }}</h1>

Placement

The schema tag should be placed at the end of your template or block file, after all other Liquid code.

Correct
Incorrect

<section class="hero">
  <h1>{{ block.heading }}</h1>
</section>

{% schema %}
{
  "name": "hero",
  "settings": [...]
}
{% endschema %}

{% schema %}
{
  "name": "hero",
  "settings": [...]
}
{% endschema %}

<section class="hero">
  <h1>{{ block.heading }}</h1>
</section>