Section and block schema

The schema tag decides which settings a section exposes in the editor. Without a schema the section still renders, but shows no settings in the editor.

The schema tag

The schema is a single JSON object inside the section file. The example below is the complete section from the Write Your First Theme guide.

sections/karsilama.zone

<section class="karsilama">
  <h1>{{ section.settings.baslik }}</h1>
  {% if section.settings.alt_yazi_goster %}
    <p>{{ 'karsilama.alt_yazi' | t }}</p>
  {% endif %}
  <ul>
    {% for block in section.blocks %}
      {% render 'madde', metin: block.settings.metin %}
    {% endfor %}
  </ul>
</section>

{% schema %}
{
  "name": "Karşılama",
  "max_blocks": 6,
  "settings": [
    { "type": "text", "id": "baslik", "label": "Başlık", "default": "Hoş geldiniz" },
    { "type": "checkbox", "id": "alt_yazi_goster", "label": "Alt yazıyı göster", "default": true }
  ],
  "blocks": [
    {
      "type": "madde",
      "name": "Madde",
      "settings": [
        { "type": "text", "id": "metin", "label": "Metin", "default": "Yeni madde" }
      ]
    }
  ],
  "presets": [
    { "name": "Karşılama" }
  ]
}
{% endschema %}

Schema keys

Only the keys below are accepted at the top level of a schema; any other key is a validation error. name is required.

Key	Description
`blocks`	The block types the section accepts and their settings.
`class`	A class added to the wrapper (next to stokzone-section).
`default`	The default configuration used when the section is placed statically in a template.
`disabled_on`	Which templates the section may not be used on. Passed to the editor; not enforced by the server for theme sections.
`enabled_on`	Which templates the section may be used on. Passed to the editor; not enforced by the server for theme sections.
`limit`	How many times the section may be used on a page. Passed to the editor; not enforced by the server for theme sections.
`locales`	The section's own translations: keys under a language code. The t filter checks theme locales first, then these.
`max_blocks`	The maximum number of blocks in the section. Enforced when the editor saves.
`name`	The section's name in the editor. Required.
`presets`	Ready-made configurations. A section without a preset does not appear in the editor's Add section list.
`settings`	The section's settings, read through section.settings by the setting's id.
`tag`	The HTML element wrapping the section. Disallowed values fall back to div.

Setting types

The setting types accepted by the engine are listed below. A type that is not on the list is a validation error. Layout types (header, paragraph) carry no value; every other setting requires id and label. If a setting has no default, the type's natural default is used.

Type	Default
`article`	`null`
`article_list`	`[]`
`blog`	`null`
`checkbox`	`false`
`collection`	`null`
`collection_list`	`[]`
`color`	`null`
`color_background`	`null`
`color_palette`	`null`
`color_scheme`	`null`
`color_scheme_group`	`null`
`font_picker`	`null`
`header`	layout only
`html`	`""`
`image_picker`	`null`
`inline_richtext`	`""`
`link_list`	`null`
`liquid`	`""`
`metaobject`	`null`
`metaobject_list`	`[]`
`number`	`null`
`page`	`null`
`paragraph`	layout only
`product`	`null`
`product_list`	`[]`
`radio`	`null`
`range`	`null`
`richtext`	`""`
`select`	`null`
`text`	`""`
`text_alignment`	`"left"`
`textarea`	`""`
`url`	`null`
`video`	`null`
`video_url`	`null`

Blocks

Blocks are items a merchant can add and reorder inside a section. In the template you loop over section.blocks; each block has type and settings. In a JSON template blocks are defined under blocks and ordered with block_order.

Zone

{% for block in section.blocks %}
  <li>{{ block.settings.metin }}</li>
{% endfor %}

Theme blocks live in separate files in the blocks/ folder and are rendered inside a section with content_for 'blocks'; a single static block is rendered with content_for 'block' given a type and id. Blocks can nest up to 8 levels deep. A block type without a file is skipped.

Zone

{% content_for 'blocks' %}
{% content_for 'block', type: 'baslik', id: 'sabit-baslik' %}

Wrapper and the editor

Every section is rendered wrapped in an element carrying its id; the engine adds the wrapper, do not write it yourself. The schema's tag key picks the element and class adds a class.

HTML

<div id="stokzone-section-karsilama-1" class="stokzone-section">
  ...
</div>

Validation

The schema validator reports all errors together: missing name, unknown key, unknown setting type, missing id or label. If the schema body is not valid JSON the section fails. The code editor still saves a file with a syntax error and shows the error with its line and column.