Schema reference | Documentação para Web Designers

O schema é a peça de maior impacto em um novo Theme (baseado em seções e blocos): define o que o usuário pode configurar no Brand Editor. Cada section e block declara seu schema ao final do arquivo entre {% schema %} e {% endschema %}. Os settings globais do Theme são declarados em config/settings_schema.json.

Tipos de setting

Todos os settings seguem esta estrutura base:

{
  "type": "setting",
  "setting_type": "<type>",
  "id": "<unique_id>",
  "label": "t:settings.<key>",
  "default": "<value>"
}

`setting_type`	Caso de uso
`text`	Texto de uma única linha.
`richtext`	Texto enriquecido com formatação inline.
`html`	Editor de HTML puro.
`url`	Seletor de link.
`select`	Dropdown — ideal para muitas opções.
`radio`	Seleção visual única — ideal para 2 a 4 opções.
`toggle`	Switch on/off.
`checkbox`	On/off legado — preferir `toggle` em settings novos.
`range`	Slider numérico com `min`, `max`, `step` e `unit`.
`color`	Seletor de cor. Usar `default_setting` para herdar uma cor global.
`image_picker`	Upload de imagem.
`text_alignment`	Alinhamento esquerda / centro / direita.
`alignment`	Grade de alinhamento 2D (vertical + horizontal).

Chaves adicionais de schema

Chave	O que faz
`default_setting`	Herda o valor padrão de um setting global em `config/settings_schema.json`. Exemplo: `"default_setting": "button_background_color"`.
`visible_if`	Exibe o setting condicionalmente conforme o valor de outro setting. Exemplo: `"visible_if": "{{ block.settings.mobile_font_size }}"`.
`disabled_if`	Desabilita o setting condicionalmente sem ocultá-lo.
`tags`	Em um block: marca-o como disponível para qualquer section que aceite essa tag.
`icon`	Ícone exibido junto ao nome da section ou block no editor.

As entradas header ({ "type": "header", "content": "t:names.design" }) não são inputs: são divisores visuais que agrupam settings no painel do editor.

Painel de settings

No editor, cada section e cada block tem seu próprio painel de settings. A forma desse painel é determinada pelo array settings do schema:

Os settings são renderizados na ordem em que são declarados.
As entradas header dividem o painel em grupos com título (ex. Design, Cores, Layout, Mobile).
visible_if / disabled_if em settings individuais permitem exibir ou desabilitar um setting conforme o valor de outro.

Exemplo de array de settings com divisores e visibilidade condicional:

"settings": [
  { "type": "header", "content": "t:names.design" },
  {
    "type": "setting",
    "setting_type": "radio",
    "id": "width",
    "label": "t:settings.section_width",
    "options": [
      { "value": "fit",  "label": "t:options.fit" },
      { "value": "fill", "label": "t:options.fill" }
    ],
    "default": "fill"
  },
  { "type": "header", "content": "t:names.text_settings" },
  {
    "type": "setting",
    "setting_type": "select",
    "id": "size",
    "label": "t:settings.size",
    "options": [
      { "value": "h1", "label": "t:options.heading_1" },
      { "value": "h2", "label": "t:options.heading_2" }
    ],
    "default": "h4"
  },
  {
    "type": "setting",
    "setting_type": "range",
    "id": "mobile_font_size",
    "label": "t:settings.mobile_font_size",
    "min": 12,
    "max": 48,
    "step": 1,
    "unit": "px",
    "default": 16
  },
  {
    "type": "setting",
    "setting_type": "select",
    "id": "mobile_size_override",
    "label": "t:settings.mobile_size_override",
    "visible_if": "{{ section.settings.mobile_font_size }}",
    "options": [ ... ],
    "default": "h4"
  }
]

Global settings

Os settings de escopo global são declarados em config/settings_schema.json. Cada entrada define um painel com nome e usa a mesma estrutura type + setting_type + id + label + default dos settings de sections e blocks.

Chaves de cada painel de settings globais:

Chave	O que faz
`name`	Nome do painel no editor (chave `t:`).
`icon`	Ícone exibido junto ao nome do painel na sidebar.
`group`	Agrupa vários painéis sob uma categoria recolhível na sidebar. Todos os painéis com o mesmo `group` aparecem aninhados sob esse rótulo. Os painéis sem `group` aparecem no nível superior.
`settings`	Array de definições de settings e divisores `header`, com a mesma forma que em sections e blocks.

Exemplo de entrada em config/settings_schema.json:

{
  "name": "t:names.colors",
  "icon": "ColorPaletteIcon",
  "group": "t:names.brand",
  "settings": [
    { "type": "header", "content": "t:content.main_colors" },
    { "type": "setting", "setting_type": "color", "id": "background_color", "label": "t:settings.background", "default": "#FFFFFF" },
    { "type": "setting", "setting_type": "color", "id": "text_color",       "label": "t:settings.text",       "default": "#3F3D38" },
    { "type": "setting", "setting_type": "color", "id": "accent_color",     "label": "t:settings.accent_color" }
  ]
}

Grupos disponíveis:

Chave `group`	Painéis que contém
`t:names.brand`	Colors, Typography, Buttons
`t:names.advanced_settings`	Browser Tab, Promotional Popup, Product Card, Product Form, Cart, Advanced CSS

Os settings globais são lidos a partir de qualquer .tpl via settings.*:

{% if settings.logo_height_desktop %}
  <img style="max-height: {{ settings.logo_height_desktop }}px" ... />
{% endif %}

Um setting de section ou block pode herdar o valor padrão de um setting global com default_setting:

{
  "type": "setting",
  "setting_type": "color",
  "id": "custom_background_color",
  "label": "t:settings.background",
  "default_setting": "button_background_color"
}

Traduções

A pasta translations/ contém dois tipos de arquivos de locale:

Padrão	Propósito	Usado por
`<locale>.json` (ex. `en.json`, `pt.default.json`)	Strings exibidas ao comprador no storefront.	`{{ 'cart.add_to_cart' \| t }}`
`<locale>.schema.json` (ex. `en.schema.json`, `es.schema.json`)	Labels exibidos ao usuário no editor.	Chaves `t:` dentro de blocos `{% schema %}`.

O prefixo t: se resolve no momento de renderizar a UI do editor, a partir dos arquivos <locale>.schema.json. O filtro | t se resolve no momento de renderizar o storefront, a partir dos arquivos <locale>.json.

As traduções de schema são objetos planos organizados por namespace:

{
  "names":      { "logo": "Logo", "heading": "Heading", "button": "Button" },
  "settings":   { "background": "Background", "format": "Format" },
  "options":    { "grid": "Grid", "slider": "Slider", "fit": "Fit", "fill": "Fill" },
  "defaults":   { "heading": "Your title here", "button": "Click me" },
  "categories": { "basic": "Basic", "media": "Media" }
}

Ao adicionar um novo setting com "label": "t:settings.minha_nova_chave", adicione minha_nova_chave ao namespace settings de todos os arquivos *.schema.json suportados.