Schema & Settings
A {% schema %} block at the top of a section declares the settings a merchant can edit. The page editor builds its settings panel from it, fills in the defaults, and checks saved values against it. The block is removed before the template renders.
A schema, live
The settings panel on the right is generated from the schema, the way the page editor generates it for a merchant. Change a value, or edit the schema and watch the panel follow.
Runs in your browser on sample data: the same engine and filters as the storefront. Widgets such as add to cart are simulated: clicking one shows what would happen on a store.
The parts of a schema
| Key | What it is |
|---|---|
name | What the section is called in the editor’s library and outline. Required. |
settings | An array of settings, in the order they appear in the panel. |
blocks | Optional. The kinds of repeatable items the section takes. See Blocks below. |
max_blocks | Optional. Most blocks in total, across all types. |
presets | Optional. Starting content, mainly which blocks a new section is created with. |
Each setting is an object with these keys:
| Key | What it does |
|---|---|
id | Unique in the section. Read it as section.settings.<id>. Letters, numbers and underscores. |
type | One of the types below. |
label | The field’s name in the panel. |
default | The value a new section starts with, and the value used whenever a saved section has none. |
info | Help text under the field. Use it for units and formats. |
options | select only: [{ "value": "…", "label": "…" }]. |
min · max · step | number and range: the bounds the panel enforces. |
Setting types
| Type | Stores | Notes |
|---|---|---|
| text | One line | — |
| textarea | Several lines, plain | — |
| rich_text | HTML from the editor | Output it directly. It is merchant content, not visitor input. |
| number | A number | min, max and step are honoured. |
| range | A number on a slider | Give it min, max and step. |
| checkbox | true or false | — |
| select | One of options[{ value, label }] | — |
| color | A hex, or a theme token as default | "default": "@color.primary" |
| image | A media-library URL | Opens the media picker. |
| url | A link | Relative paths are fine: /collections |
| menu | A navigation menu handle | Read it with linklists[section.settings.your_id]. |
| product | One product (handle or id) | Opens the product picker. Pair with product_source: "product" and read products | first. |
| blog | Blog post slugs, comma-separated | Opens the post picker. Name it article_handles with article_source: "handles" and the posts arrive in articles, in that order. |
| list | An array of items | A repeater. Declare "fields" (the settings of one item) and loop over it. Optional "max" and "item_label". |
| collection | One collection | Resolved to a collection drop: section.settings.your_id.products. |
| collection_list | Several collections | Resolved to an array of collection drops (up to 24). |
| product_list | Several products | Resolved to an array of product drops (up to 24). |
| page | One page | Resolved to { title, handle, url }. |
Grouping settings
{ "type": "header", "content": "Style" } starts a group: the settings after it appear under that heading in the panel. A header has no id and no value.
Defaults that follow the store's theme
A color default of @color.primary (or any @color.*, or @shape.radius) is the merchant's own theme colour, resolved when the section renders. The merchant still gets a picker and can override it. Every other default is literal. See Theme tokens for the full list.
Settings that fetch data
Some ids are reserved: product_source, collection_source, article_source and their companions make the storefront fetch products, collections or posts before the template runs. See Products, collections & posts. Reference types (collection, collection_list, product_list, page) also fetch: the setting stores a handle and the template reads a full object.
List settings
A list is a repeater: the merchant adds, removes and reorders items, each with the fields you declare. Use it for FAQs, testimonials, logos and slides, wherever the items are all the same shape.
fields can use any type except the reference types. max caps the number of items and item_label names one item in the editor (“Add question”).
Blocks
Blocks are like list items that can be different kinds. A section can take icons and notes, slides and videos, and the merchant mixes them in any order. Loop over section.blocks and branch on block.type.
| block. | Value |
|---|---|
| id | Unique in the section. |
| type | The block type from the schema. |
| index | Position, from 1. |
| settings | Its settings, with defaults filled in and @color.* resolved. |
| joomni_attributes | Put it on the block’s root element. It lets the editor select the block when the merchant clicks it. shopify_attributes is the same string. |
list or blocks?
list when every item has the same fields. Use blocks when items differ in kind, or when the merchant should be able to select each one on the canvas.Pasting a Shopify section
Shopify setting types are accepted and mapped to Joomni's own, so a pasted schema needs no edits:
| Shopify type | Rendered as |
|---|---|
| richtext | rich_text |
| inline_richtext | text |
| html · liquid | textarea |
| video_url · video | url |
| radio · text_alignment | select |
| link_list | menu |
| color_background · font_picker · article · metaobject | text |
@app and @theme block types are ignored. A schema with an unknown type, a duplicate id or a malformed option is rejected when the section is saved, with the setting's position in the error.