Schema reference | Documentación para Diseñadores

El schema es la pieza de mayor impacto en un nuevo Theme (basado en secciones y bloques): define qué puede configurar el administrador en el Brand Editor. Cada section y block declara su schema al final del archivo entre {% schema %} y {% endschema %}. Los settings globales del Theme se declaran en config/settings_schema.json.

Tipos de setting

Todos los settings siguen esta estructura base:

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

`setting_type`	Caso de uso
`text`	Texto de una sola línea.
`richtext`	Texto enriquecido con formato inline.
`html`	Editor de HTML crudo.
`url`	Selector de enlace.
`select`	Dropdown — ideal para muchas opciones.
`radio`	Selección visual única — ideal para 2 a 4 opciones.
`toggle`	Switch on/off.
`checkbox`	On/off heredado — preferir `toggle` en settings nuevos.
`range`	Slider numérico con `min`, `max`, `step` y `unit`.
`color`	Selector de color. Usar `default_setting` para heredar un color global.
`image_picker`	Carga de imagen.
`text_alignment`	Alineación izquierda / centro / derecha.
`alignment`	Grilla de alineación 2D (vertical + horizontal).

Claves adicionales de schema

Clave	Qué hace
`default_setting`	Hereda el valor por defecto desde un setting global en `config/settings_schema.json`. Ejemplo: `"default_setting": "button_background_color"`.
`visible_if`	Muestra el setting condicionalmente según el valor de otro setting. Ejemplo: `"visible_if": "{{ block.settings.mobile_font_size }}"`.
`disabled_if`	Deshabilita el setting condicionalmente sin ocultarlo.
`tags`	En un block: lo marca como disponible para cualquier section que acepte ese tag.
`icon`	Ícono mostrado junto al nombre de la section o block en el editor.

Las entradas header ({ "type": "header", "content": "t:names.design" }) no son inputs: son divisores visuales que agrupan settings en el panel del editor.

Panel de settings

En el editor, cada section y cada block tiene su propio panel de settings. La forma de ese panel está determinada por el array settings del schema:

Los settings se renderizan en el orden en que se declaran.
Las entradas header dividen el panel en grupos con título (ej. Diseño, Colores, Layout, Mobile).
visible_if / disabled_if en settings individuales permiten mostrar o deshabilitar un setting según el valor de otro.

Ejemplo de array de settings con divisores y visibilidad 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

Los settings de alcance global se declaran en config/settings_schema.json. Cada entrada define un panel con nombre y usa la misma estructura type + setting_type + id + label + default que los settings de sections y blocks.

Claves de cada panel de settings globales:

Clave	Qué hace
`name`	Nombre del panel en el editor (clave `t:`).
`icon`	Ícono mostrado junto al nombre del panel en el sidebar.
`group`	Agrupa varios paneles bajo una categoría colapsable en el sidebar. Todos los paneles con el mismo `group` aparecen anidados bajo esa etiqueta. Los paneles sin `group` aparecen en el nivel superior.
`settings`	Array de definiciones de settings y divisores `header`, con la misma forma que en sections y blocks.

Ejemplo de entrada en 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 disponibles:

Clave `group`	Paneles que contiene
`t:names.brand`	Colors, Typography, Buttons
`t:names.advanced_settings`	Browser Tab, Promotional Popup, Product Card, Product Form, Cart, Advanced CSS

Clave `group`	Paneles que contiene
`t:names.brand`	Colors, Typography, Buttons
`t:names.advanced_settings`	Browser Tab, Promotional Popup, Product Card, Product Form, Cart, Advanced CSS

Los settings globales se leen desde cualquier .tpl vía settings.*:

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

Un setting de section o block puede heredar el valor por defecto de un setting global con default_setting:

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

Traducciones

La carpeta translations/ contiene dos tipos de archivos de locale:

Patrón	Propósito	Usado por
`<locale>.json` (ej. `en.json`, `pt.default.json`)	Strings mostrados al comprador en el storefront.	`{{ 'cart.add_to_cart' \| t }}`
`<locale>.schema.json` (ej. `en.schema.json`, `es.schema.json`)	Labels mostrados al usuario en el editor.	Claves `t:` dentro de bloques `{% schema %}`.

El prefijo t: se resuelve al momento de renderizar la UI del editor, desde los archivos <locale>.schema.json. El filtro | t se resuelve al momento de renderizar el storefront, desde los archivos <locale>.json.

Las traducciones de schema son objetos planos organizados por espacio de nombres:

{
  "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" }
}

Al agregar un nuevo setting con "label": "t:settings.my_new_label", se debe agregar my_new_label al espacio de nombres settings de todos los archivos *.schema.json soportados.