> ## Documentation Index
> Fetch the complete documentation index at: https://allbay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema

> Defina opções editáveis no painel — sem tocar no código do tema.

O schema define as opções de personalização que aparecem no painel. Assim o dono da loja
ajusta cores, textos e imagens sem editar código.

O arquivo é `config/settings_schema.json`.

> [!NOTE]
>
> Os temas **Vega**, **Orion**, **Altair** e **Lyra** (e os forks deles) usam, no painel, o schema
> **mantido pela AllBay** para aquele tema. **Rigel**, **Sirius** e **Antares** usam o próprio
> `config/settings_schema.json`.

## Estrutura

```json theme={null}
{
  "settings": [
    {
      "title": "Cores",
      "fields": [
        {
          "key": "primary_color",
          "label": "Cor primária",
          "description": "Cor principal da loja",
          "type": "color",
          "default": "#5865F2"
        }
      ]
    }
  ]
}
```

* Cada grupo tem `title` (ou `name`) e `fields` (ou `settings`).
* Cada campo tem `key` (ou `id`), `label`, `type`, e opcionalmente `description` e `default`.
* Limites: 50 grupos, 200 campos, 100 opções por `select`.

## Chaves dos campos

A `key` precisa começar com letra e usar só **letras, números e `_`** (até 64 caracteres).

> [!WARNING]
>
> **Hífen não é permitido.** Um campo com `"key": "primary-color"` é **ignorado**. Use
> `primary_color`.

## Acessando os valores

Os valores ficam no global `config` (e em `settings`), com a mesma chave do campo:

| Chave no schema | Acesso no Liquid |
| - | - |
| `primary_color` | `config.primary_color` |
| `hero_image` | `config.hero_image` |

```liquid theme={null}
<style>:root{ --primary: {{ config.primary_color | hex_to_hsl }}; }</style>
{% if config.hero_image %}<img src="{{ config.hero_image }}" alt="">{% endif %}
```

Um campo sem valor usa o `default` — desde que o tema tenha o próprio
`config/settings_schema.json`. Sem esse arquivo, os valores chegam como foram salvos; use
`| default:` no Liquid. Imagens já chegam como URL pronta (ver [Imagens](https://allbay.mintlify.site/editor/imagens.md)).

## Tipos de campo

| Tipo | Guarda | Observação |
| - | - | - |
| `text` | texto de uma linha | até 5000 caracteres (`max_length` reduz) |
| `textarea` | texto | até 20000 caracteres (`max_length` reduz) |
| `wysiwyg` | HTML (editor rico) | até 40000 caracteres |
| `color` (`color-picker`) | cor | exatamente `#RRGGBB` |
| `number` (`range`) | número **inteiro** | aceita `min`/`max` |
| `checkbox` (`boolean`) | verdadeiro/falso | |
| `select` | uma opção | requer `options` |
| `url` | link | `https://…`, `http://…` ou caminho `/…` |
| `image` (`image_picker`) | imagem | chega como URL pronta |
| `images` | várias imagens | `max_items` (padrão 5, máx. 20) |
| `array` | lista de itens | itens com `fields` próprios (ver abaixo) |
| `products` (`product`, `packages`) | seleção de produtos | `max_items` (padrão 12, máx. 100) |

> [!NOTE]
>
> `textarea` hoje **não aceita quebras de linha**. Para textos com parágrafos, use `wysiwyg`.

### `array`

Cada item tem até 20 campos, dos tipos `text`, `checkbox`, `number`, `select`, `color`,
`url`, `image` e `products`. `max_items`: padrão 50, máximo 200.

```json theme={null}
{
  "key": "faq",
  "label": "Perguntas frequentes",
  "type": "array",
  "fields": [
    { "key": "question", "label": "Pergunta", "type": "text" },
    { "key": "answer", "label": "Resposta", "type": "text" }
  ]
}
```

```liquid theme={null}
{% for item in config.faq %}
  <h3>{{ item.question }}</h3><p>{{ item.answer }}</p>
{% endfor %}
```

> [!WARNING]
>
> Um campo `image` dentro de um item de `array` hoje **não pode ser exibido** no tema. Use
> campos `image`/`images` no primeiro nível do schema.

## Exemplo com vários campos

```json theme={null}
{
  "settings": [
    {
      "title": "Cabeçalho",
      "fields": [
        { "key": "logo", "label": "Logo", "type": "image" },
        { "key": "fixed_header", "label": "Cabeçalho fixo", "type": "checkbox", "default": true },
        {
          "key": "layout", "label": "Layout", "type": "select",
          "options": [{ "value": "wide", "label": "Largo" }, { "value": "boxed", "label": "Caixa" }],
          "default": "wide"
        }
      ]
    },
    {
      "title": "Destaques",
      "fields": [
        { "key": "featured", "label": "Produtos em destaque", "type": "products", "max_items": 4 }
      ]
    }
  ]
}
```

## Validação

O servidor valida cada valor pelo tipo: `color` só aceita `#RRGGBB`, `select` só aceita as
`options`, `number` respeita `min`/`max`, `url` não aceita `javascript:`. Valores inválidos ou
chaves que não existem no schema são **recusados**, com a lista de erros.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.