> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema Contract

> Contrato canônico de schemas — section, block e theme settings.

> Esta página é o **contrato canônico** para schemas de settings na Corvex.

Schemas JSON definem **o que o merchant pode editar** no Inspector. O runtime passa os valores salvos como `settings` (section/block) ou theme settings globais.

***

## Tipos de schema

| Schema | Arquivo | Consumidor |
| - | - | - |
| Section | `sections/{id}/schema.json` | Inspector da section → `props.settings` |
| Block | `blocks/{id}/schema.json` | Inspector do block → `props.settings` |
| Theme | `config/settings.schema.json` | Painel Tema global |

***

## MUST — section `schema.json`

| Campo | Obrigatório |
| - | - |
| `name` | REQUIRED |
| `category` | REQUIRED |
| `nameAliases` | OPTIONAL — strings de `name` antigas ainda presentes em rascunhos; o host registra. Não atribua no componente. Ver [identidade](https://docs-loja.usecorvex.com.br/reference/contracts/section.md#identidade-type-estável-name-livre) |
| `settings` | OPTIONAL — array |
| `enabledOn` | OPTIONAL — `PageType[]` |
| `data` | OPTIONAL — `SectionDataKey[]` |

Interface TypeScript: `SectionSchema` em `@corvex/theme-sdk` types.

***

## MUST — block `schema.json`

| Campo | Obrigatório |
| - | - |
| `name` | REQUIRED |
| `nameAliases` | OPTIONAL — igual à section |
| `settings` | OPTIONAL |
| `type` | SHOULD |

***

## MUST — theme `settings.schema.json`

| Campo | Obrigatório |
| - | - |
| `groups` | REQUIRED — `Array<{ name, settings[] }>` |

| Campo | Opcional |
| - | - |
| `color_schemes` | OPTIONAL |
| `defaults` | OPTIONAL |
| `settings` | OPTIONAL — legado flat |

Interface: `ThemeSettingsSchema`.

***

## MUST — field definition (campos com `id`)

Cada setting com valor persistido MUST ter:

| Propriedade | Obrigatório |
| - | - |
| `id` | REQUIRED |
| `type` | REQUIRED |
| `label` | SHOULD |

Propriedades comuns OPTIONAL: `default`, `info`, `placeholder`, `visibleWhen`.

`default` é o valor inicial de **um campo**. Layout inicial da loja na instalação vai em `templates/*.json` ([theme-defaults](https://docs-loja.usecorvex.com.br/guides/theme-defaults.md)).

### OPTIONAL — `presets` (section e block)

Array de variantes para o editor (**Adicionar seção** / **Adicionar bloco**). Cada item: `name` (REQUIRED), `category` (OPTIONAL), `settings` (OPTIONAL), e em **sections** `blocks` (OPTIONAL, array `{ type, settings? }`). Validação: `@corvex/theme-contract`. Guia: [section-presets](https://docs-loja.usecorvex.com.br/guides/section-presets.md).

`visibleWhen` controla visibilidade no Inspector com base em outros settings — ver [visibleWhen](https://docs-loja.usecorvex.com.br/schema/visible-when.md).

***

## MUST — field types estáveis (section / block)

Lista estável em `@corvex/theme-contract` (`STABLE_SETTING_TYPES`). O validador aceita estes tipos:

`text`, `textarea`, `richtext`, `number`, `range`, `color`, `checkbox`, `select`, `radio`, `image`, `image_picker`, `url`, `product`, `product_list`, `collection`, `collection_list`, `font_picker`, `color_scheme`, `menu`, `header`, `paragraph`

Detalhes por tipo: [Schema overview](https://docs-loja.usecorvex.com.br/schema/overview.md).

> [!NOTE]
>
> O editor também renderiza tipos experimentais (`EXPERIMENTAL_SETTING_TYPES`): `inline_richtext`, `html`, `video`, `video_url`, `page`, `blog`, `link_list`. O validador aceita. Eles não fazem parte do contrato estável.

***

## MUST — campos sem `id` (layout)

| `type` | Uso |
| - | - |
| `header` | Título de grupo — prop `content` |
| `paragraph` | Texto de ajuda — prop `content` |

***

## MUST — `select` / `radio`

`options` REQUIRED:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "value": "small", "label": "Pequena" }
```

Valor salvo: `string` do `value` selecionado.

***

## MUST — `range`

`min` e `max` REQUIRED no schema. Valor salvo: `number`.

***

## OPTIONAL — `color` com `themeLink`

Vincula o campo a uma theme setting global (referência `@theme.{key}`). Ver guias de theme settings.

***

## Valores salvos

* Settings são JSON serializável no draft da loja.
* MUST NOT assumir tipos não definidos pelo field type (ex.: `product` salva ID string UUID).

***

## Veja também

* [Organização de schemas](https://docs-loja.usecorvex.com.br/guides/schema-organization.md) — boas práticas de UX no Inspector
* [Schema overview](https://docs-loja.usecorvex.com.br/schema/overview.md) — referência por field type


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