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
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).

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.

visibleWhen controla visibilidade no Inspector com base em outros settings — ver visibleWhen.

---

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.

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:

{ "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 — boas práticas de UX no Inspector
• Schema overview — referência por field type