] } // "or" igual; "negate": true inverte
```
- `source.kind`: `question` (+`questionId`, e `sub` para linha de matriz), `variable` (+`name`),
`calculated` (+`name`), `device` (`"mobile"`/`"desktop"`), `random_pct` (0 a 99).
- Operadores: `selected`, `not_selected`, `any_selected`, `none_selected`, `all_selected`
(estes três com lista), `selected_count_eq`/`_gte`/`_lte`, `eq`, `neq`, `gt`, `gte`, `lt`,
`lte`, `between` (`[mín, máx]`), `contains`, `not_contains`, `matches_regex` (texto),
`is_answered`, `is_not_answered`, `rank_of_eq`/`rank_of_lte` (`{"optionId","rank"}`).
- Exemplos: respondeu? `{"source":{"kind":"question","questionId":"P7"},"operator":"is_answered"}`;
idade entre 18 e 24: `{"source":{"kind":"question","questionId":"idade"},"operator":"between","operand":[18,24]}`.
### 6.3 Onde cada forma vale
| Lugar | Forma curta `{"if"}` | Forma completa |
|---|---|---|
| `displayIf`/`requiredIf` de pergunta, opção, página, bloco | sim | sim |
| `enableIf` de opção | sim | sim |
| `displayIf` de texto, imagem e grupo | sim | sim |
| `skipTo[].if` e `condition` do `branch` | sim | sim |
| `condition` de célula de cota (`_quotas`) e `if` de gatilho (`triggers`) | sim | sim |
Nunca escreva `{"all": [...]}`, `{"any": [...]}` nem `{"if": "...", "outra": ...}`: o validador
os recusa (`CONDITION_MALFORMED`), e antes eles quebravam a coleta. Combine com `and`/`or` na
forma curta ou com `op` na completa.
---
## 7. Fluxo, triagem, encerramentos e cotas
### 7.1 `flow` e `endings`
Sem `flow`: os blocos na ordem e um fim "complete". Com `flow`:
| Nó | Forma |
|---|---|
| bloco | `{"kind":"block","blockId":"B1"}` |
| desvio | `{"kind":"branch","condition":{"if":"..."},"children":[ ...nós... ]}` — os filhos só rodam se a condição for verdadeira |
| encerramento | `{"kind":"ending","endingId":"fim"}` |
| corte de cota | `{"kind":"quota_check","quotaId":"cafe2026_sexo"}` |
| gravar variável | `{"kind":"set_variables","assignments":[{"name":"trilha","value":"A"}]}` (8.3) |
```jsonc
"endings": [
{ "id":"fim", "status":"complete", "label":"Fim", "message":"Obrigado por participar!" },
{ "id":"filtro", "status":"terminated", "label":"Não elegível", "message":"Obrigado! A pesquisa não segue para você." },
{ "id":"cheia", "status":"overquota", "label":"Cota cheia", "message":"Obrigado! Já temos respostas suficientes do seu perfil." }
]
```
`status`: `complete` (respondeu tudo) · `terminated` (filtrado na triagem) · `overquota` (cota
cheia) · `quality_terminated` (barrado por qualidade, 10.7). Declare todo encerramento que o
`skipTo` ou o `flow` citar. O link de retorno para o painel não entra no JSON: ele é
configurado no coletor, na Upinion.
### 7.2 Triagem (filtro)
A forma recomendada é um `skipTo` na própria pergunta-filtro para um encerramento
`terminated`, com `"screenoutMode": "immediate"` em `meta`:
```jsonc
{ "id":"idade", "type":"numeric", "text":"Qual a sua idade?", "min":0, "max":120,
"skipTo":[ {"if":"idade < 18", "target":{"kind":"ending","endingId":"filtro"}} ] }
```
Um `branch` no fluxo com um nó `ending` dentro também encerra, mas só quando o fluxo chega
nele (depois do bloco anterior inteiro).
### 7.3 Pular para outra parte
`skipTo` com `"kind": "page"` ou `"kind": "block"`. Para desviar blocos inteiros por perfil,
use `branch` no fluxo.
### 7.4 Cotas
Cada cota tem células (condição + alvo). Ponha um `quota_check` no fluxo **depois** do bloco em
que o perfil é respondido: quem cai numa célula cheia vai para o encerramento `overquota`.
A condição da célula aceita as duas formas (6.3). Ids levam o nome do estudo.
```jsonc
"_quotas": [ { "id":"cafe2026_sexo", "name":"Sexo", "cells": [
{ "id":"cafe2026_sexo_f", "name":"Feminino", "target":150,
"condition": {"source":{"kind":"question","questionId":"sexo"},"operator":"selected","operand":"f"} },
{ "id":"cafe2026_sexo_m", "name":"Masculino", "target":150,
"condition": {"source":{"kind":"question","questionId":"sexo"},"operator":"selected","operand":"m"} } ] } ],
"flow": [ {"kind":"block","blockId":"B_perfil"}, {"kind":"quota_check","quotaId":"cafe2026_sexo"},
{"kind":"block","blockId":"B_main"}, {"kind":"ending","endingId":"fim"} ]
```
- Cota cruzada (sexo × região): uma célula por combinação, com `{"op":"and","children":[...]}`.
- Faixa de idade: `"operator":"between","operand":[18,24]`.
- `target` 0 ou ausente = célula sem limite.
---
## 8. Variáveis, URL, calculadas e piping
### 8.1 Variáveis (`variables`)
```jsonc
"variables": [ {"name":"canal","type":"text","defaultValue":"site","exportable":true} ]
```
- Todo parâmetro do link de entrada chega como variável pelo nome: `...?canal=email` faz
`{var.canal}` valer `email`. O valor da URL vence o `defaultValue`.
- `type`: `text` ou `number`. Nome: letra, depois letras/números/`_`. Não use `c`, `score` nem
nome começando com `_`.
- Declare a variável para usá-la em condição.
- Os parâmetros de painel (`rid`, `pid`, `gid`, `psid`, `utm_*`) já chegam sozinhos: **não os
declare**, a não ser que precise ramificar por eles (nesse caso declare sem `defaultValue`).
### 8.2 Calculadas (`calculated`)
```jsonc
"calculated": [
{"name":"faixa","expression":"iif({idade} >= 45, 'madura', iif({idade} >= 30, 'media', 'jovem'))",
"recompute":"on_page_submit","exportable":true}
]
```
- Referências entre chaves: `{idade}` (resposta), `{sat.r1}` (linha), `{var.x}`, `{calc.x}`.
Comparação com o rótulo de uma opção funciona: `{P1} = 'Pilão'`.
- Operadores `+ - * / %`, comparações, `and or not`, listas `['a','b']`.
- Funções: `sum min max round abs len count iif age answered contains`, e as de conjunto
`union(a,b)`, `diff(a,b)`/`exclude(a,b)`, `intersect(a,b)`.
- Para sortear, **não** use calculada: use `draws` (seção 9).
### 8.3 Gravar uma variável no meio do fluxo
```jsonc
{"kind":"set_variables","assignments":[
{"name":"trilha","value":{"expr":"iif({idade} >= 40, 'senior', 'jovem')"}} ]}
```
`value` é um literal (`"A"`, `10`) ou `{"expr": "..."}`. A variável precisa estar declarada.
### 8.4 Piping (inserir resposta no texto)
`"text": "Por que você deu nota {{P5_nps}} para a {{draw.marca}}?"`
- Refs: `{{P5_nps}}` (resposta), `{{var.canal}}`, `{{calc.faixa}}`, `{{draw.marca}}` (rótulo
sorteado), `{{loop.label}}` (item do loop).
- Funciona em: enunciado e `description` da pergunta, `html` de texto, legenda de imagem,
títulos de página e bloco, e `message` de encerramento.
- **Não funciona** em rótulo de opção, linha ou coluna.
---
## 9. Sorteio (`draws`)
Sorteia item(ns) para cada respondente. O valor congela: voltar e mudar a resposta não sorteia
de novo.
```jsonc
"draws": [ { "name":"marca", "source":{"questionId":"conhece"},
"exclude":"['outro','nenhuma']", "balance":true,
"whenEmpty":"screenout", "whenEmptyEndingId":"filtro", "exportable":true } ]
```
- `name`: nome do sorteio (regras de nome de variável).
- `source` (uma das três):
- pergunta: `{"questionId":"conhece","pool":"selected"}` — `pool`: `selected` (padrão),
`not_selected`, `all`, ou `ranked_top_n` + `topN` (os N primeiros de um `rank_order`);
- lista fixa: `{"items":[{"id":"pilao","label":"Pilão"}, ...]}`;
- fórmula: `{"expression":"..."}` que devolve uma lista de ids.
- `count`: quantos itens sortear (1 a 50; padrão 1).
- `exclude`: fórmula com os ids que não entram (ex.: `"['outro','nenhuma']"`).
- `balance`: `true` equilibra quantas vezes cada item sai entre os respondentes (padrão `false`).
- `target`: meta de completas para **cada** item (com `balance`, o sorteio corre atrás dela);
`targetByItem` (`{"pilao":100}`) dá a um item uma meta própria. Meta 0 = sem meta.
- `fallbackSources`: lista de fontes extras (mesma forma de `source`) que completam a vaga
quando a principal não tem itens suficientes.
- `whenEmpty`: `empty` (padrão: segue com o sorteio vazio) ou `screenout` (encerra na hora;
exige `whenEmptyEndingId` apontando para um encerramento `terminated` declarado). Quando a
fonte tem "Outro" ou "Nenhuma" no `exclude`, quem marcou só eles fica sem item: use
`screenout`, senão o enunciado com `{{draw.x}}` aparece com um buraco no lugar da marca.
Como usar o valor:
- No texto: `{{draw.marca}}` mostra o rótulo. Com `count` maior que 1, `{{draw.marca}}` lista
todos, e `{{draw.marca1}}`, `{{draw.marca2}}`… mostram cada vaga.
- Na condição: `{var.marca} == 'pilao'` (o id). Vaga preenchida?
`{"source":{"kind":"variable","name":"marca2"},"operator":"is_answered"}`.
- Para uma pergunta por item sorteado, faça uma pergunta por vaga (`nota_marca1`,
`nota_marca2`), com o rótulo no enunciado.
---
## 10. Recursos avançados
### 10.1 Herança de lista — "só as marcas citadas antes"
Cada opção da pergunta que herda tem um `displayIf` que olha a mesma opção numa pergunta
anterior. A pergunta-fonte precisa estar numa **página anterior**.
```jsonc
// página 1
{ "id":"conhece", "type":"multi_choice", "text":"Quais marcas você conhece?",
"options":[{"id":"nu","label":"Nubank"},{"id":"it","label":"Itaú"},{"id":"pp","label":"PicPay"}] }
// página seguinte
{ "id":"usa", "type":"multi_choice", "text":"Das que conhece, quais você usa?",
"options":[
{"id":"nu","label":"Nubank","displayIf":"conhece == 'nu'"},
{"id":"it","label":"Itaú","displayIf":"conhece == 'it'"},
{"id":"pp","label":"PicPay","displayIf":"conhece == 'pp'"}] }
```
- Opção sem `displayIf` aparece para todos (ex.: uma "Outra" fixa).
- Herdar de duas perguntas: `"displayIf": "bancos == 'nu' or cartoes == 'nu'"`.
- As **não** citadas: `"displayIf": "conhece != 'nu'"`.
- Para mostrar só N das herdadas: some `"optionRandomization":{"strategy":"subset_n","subsetN":3}`.
### 10.2 Bloco em loop — repetir perguntas por item
Um bloco com `loop` repete suas páginas para cada item. A pergunta-fonte fica num **bloco
anterior** (nunca dentro do próprio bloco em loop).
```json
{
"meta": { "title": "Avaliação por banco", "screenoutMode": "immediate" },
"blocks": [
{ "id":"B_conhece", "pages":[ { "elements":[
{ "id":"conhece", "type":"multi_choice", "text":"Quais bancos você conhece?",
"options":[ {"id":"nu","label":"Nubank"}, {"id":"it","label":"Itaú"},
{"id":"pp","label":"PicPay"} ] } ] } ] },
{ "id":"B_aval",
"loop": { "sourceQuestionId":"conhece", "pool":"selected", "max":2 },
"pages":[ { "elements":[
{ "id":"nota", "type":"nps", "text":"De 0 a 10, quanto você recomendaria o {{loop.label}}?" },
{ "id":"motivo", "type":"text_long", "required":false, "text":"Por quê?" } ] } ] }
]
}
```
- `pool`: como no sorteio (`selected`, `not_selected`, `all`, `ranked_top_n` + `topN`).
Fonte de resposta única: use `"pool":"all"`.
- `max`: teto de itens (padrão 8); acima dele, sorteia `max` itens, estável por respondente.
`"randomizeOrder": true` embaralha a ordem.
- Catálogo fixo em vez de pergunta: `"catalog":[{"id":"pulse","label":"Fiat Pulse","weight":2,
"category":"suv","image":"https://..."}, ...]` + `max`; opc: `minCategories` (mistura de
categorias). O sorteio respeita `weight`.
- Imagem por item: `"images":{"nu":"https://..."}`; no texto, `{{loop.image}}`.
- Piping: `{{loop.label}}`, `{{loop.id}}`, `{{loop.index}}`. As respostas ficam por item
(`nota#nu`, `nota#it` na exportação).
### 10.3 Randomização
- Opções: `"optionRandomization": {"strategy": "shuffle"}`. Estratégias: `shuffle`,
`rotation`, `reverse_random`, `alphabetical`, `subset_n` (+ `"subsetN": 3`, mostra só N),
`shuffle_groups` e `groups_and_items` (pelo `group` de cada opção). "Outro", "Nenhuma" e
opções com `"fixedPosition": true` não saem do lugar.
- Linhas de matriz: `"rowRandomization": {"strategy": "shuffle"}`.
- Páginas de um bloco: `"randomization": {"mode": "shuffle_pages"}` no bloco. Para rodar
perguntas, ponha uma por página nesse bloco.
- Blocos inteiros: um nó `randomizer` no `flow`, com os blocos dentro dele e não soltos ao
lado. `presentCount` mostra só N deles por pessoa (`null` mostra todos):
`{"kind": "randomizer", "id": "R1", "presentCount": null, "evenly": false,
"children": [{"kind": "block", "blockId": "B_marcaA"}, {"kind": "block", "blockId": "B_marcaB"}]}`.
Cada bloco aparece inteiro, com as páginas na ordem dele. Com `presentCount`, cada bloco
tem a mesma chance, sorteada pessoa a pessoa: `evenly` ainda não reparte por contador.
- Perguntas de uma página: ponha-as num grupo,
`{"kind": "group", "randomizeElements": true, "elements": [ ...perguntas... ]}`. No
construtor ele aparece como "embaralhar as perguntas da página"; título e condição no grupo
não são editáveis lá, então prefira a condição na página.
- A ordem sorteada fica gravada por respondente.
### 10.4 Teste A/B do enunciado
```jsonc
{ "id":"cta", "type":"single_choice", "text":"(texto padrão)",
"abTest": { "variants": [
{"id":"v1","text":{"pt-BR":"Você compraria este produto?"}},
{"id":"v2","text":{"pt-BR":"Você recomendaria este produto a um amigo?"}} ] },
"options":[{"id":"s","label":"Sim"},{"id":"n","label":"Não"}] }
```
Cada respondente vê uma variante, e a variante fica gravada. O texto da variante é sempre
objeto por idioma.
### 10.5 Pontuação (quiz e índices)
Declare uma calculada que soma os pontos, comparando pelo rótulo da opção:
```jsonc
"calculated": [ {"name":"pontos", "recompute":"on_page_submit", "exportable":true,
"expression":"iif({q1} = 'Brasília', 10, 0) + iif({q2} = 'Azul', 5, 0)"} ]
```
O total aparece no texto com `{{calc.pontos}}` e entra em condição com `{calc.pontos} >= 10`.
### 10.6 Verificação entre perguntas
```jsonc
{ "id":"renda_fam", "type":"numeric", "text":"Renda familiar mensal (R$)",
"validation": { "expression":"{renda_fam} >= {renda_ind}",
"expressionMessage":"A renda familiar não pode ser menor que a sua." } }
```
A expressão usa a sintaxe das calculadas (8.2) e só é cobrada quando todas as perguntas citadas
têm resposta. Confira os ids: um id errado faz a regra nunca barrar. Para faixas de renda em
duas perguntas de escolha, prefira perguntar o valor (`numeric`).
### 10.7 Qualidade
- Pergunta de atenção: numa `single_choice`, `"isAttentionCheck": true` e
`"correctOptionId": "id_certo"`. Quem erra fica marcado na base.
- Para encerrar quem erra: `skipTo` para um encerramento `quality_terminated`. Esse
encerramento sempre espera o fim do questionário.
- Velocidade e respostas em linha reta são marcadas sozinhas.
- Para trocar os limites deste questionário, o bloco `quality` no topo:
`"quality": {"minLoiSeconds": 300, "straightliningThreshold": 0.9,
"maxFailedAttention": 1, "attentionChecksRequired": 2}`. Tempo mínimo da entrevista
completa em segundos; fração das linhas da matriz na mesma coluna; armadilhas que a
pessoa pode errar; armadilhas que ela precisa acertar (só conta a que ela viu). As
regras só marcam a resposta na pontuação de qualidade: não encerram ninguém.
### 10.8 Tema (aparência)
```jsonc
"meta": { "title":"...", "theme": {
"primaryColor":"#0f766e", "backgroundColor":"#f5f6f8", "textColor":"#151827",
"fontFamily":"inter", "logo":"https://.../logo.png", "logoPosition":"left",
"borderRadius":10, "containerWidth":720, "showUpinionFooter":true } }
```
`fontFamily`: `system`, `inter`, `roboto`, `lato`, `montserrat`, `opensans`, `poppins`,
`merriweather`. `logoPosition`: `left`, `center`, `right`.
### 10.9 Bases de dados (CSV)
`drill_down` e `autocomplete_dataset` leem uma base (CSV) da Upinion pelo `datasetId`. A base
`seed_localidades_br` (UF → Município → Bairro) já existe para todos:
```json
{ "id":"local", "type":"drill_down", "text":"Onde você mora?",
"datasetId":"seed_localidades_br", "levels":["Estado","Cidade","Bairro"] }
```
Outra base precisa ser criada antes na Upinion (menu Bases do construtor); sem ela, deixe a
pergunta como `dropdown` e registre em `_pendencias`.
### 10.10 Idiomas
Com `"locales": ["pt-BR","en"]`, escreva todo texto como objeto: `{"pt-BR":"Idade?","en":"Age?"}`.
Texto faltando num idioma vira aviso `TRANSLATION_MISSING`.
### 10.11 Imagens
Toda imagem (`image` de opção, `heatmap_click`, `hotspot`, `kind: image`, `logo`) é uma URL
pública `https://`. Se o documento só traz a imagem colada, use um endereço provisório e
registre em `_pendencias` para trocar no construtor.
---
## 11. Métodos de pesquisa de mercado
### 11.1 Conjoint (CBC)
O exercício fica em `exercises.cbc[]` (atributos × níveis + configuração) e há uma pergunta
`cbc_task` por tarefa, uma por página, com `exerciseId` e `taskIndex` (de 0 a
`tasksPerRespondent - 1`). Os conceitos de cada tarefa são gerados pela Upinion ao publicar.
```jsonc
{
"exercises": { "cbc": [ {
"id": "E1",
"attributes": [
{ "id":"marca", "name":"Marca",
"levels":[ {"id":"m1","label":"Marca A"}, {"id":"m2","label":"Marca B"} ] },
{ "id":"preco", "name":"Preço",
"levels":[ {"id":"p1","label":"R$ 9,90"}, {"id":"p2","label":"R$ 14,90"} ] }
],
"tasksPerRespondent": 8, // nº de telas de escolha
"conceptsPerTask": 3, // opções por tela
"noneOption": "traditional", // "traditional" mostra "Nenhuma"; "none" oculta
"designMethod": "balanced_overlap",
"designVersions": 20, "seed": 42
} ] },
"blocks": [ { "id":"B_cbc", "pages": [
{ "elements":[ {"id":"CBC1","type":"cbc_task","text":"Qual escolheria?","exerciseId":"E1","taskIndex":0} ] },
{ "elements":[ {"id":"CBC2","type":"cbc_task","text":"Qual escolheria?","exerciseId":"E1","taskIndex":1} ] }
// ... uma página por tarefa
] } ]
}
```
### 11.2 MaxDiff (melhor e pior)
Igual ao CBC, com uma lista de itens. Regra: **nº de itens ≥ 2 × `itemsPerTask`**.
```jsonc
{
"exercises": { "maxdiff": [ {
"id":"M1",
"items":[ {"id":"i1","label":"Preço baixo"}, {"id":"i2","label":"Entrega rápida"},
{"id":"i3","label":"Boa marca"}, {"id":"i4","label":"Atendimento"},
{"id":"i5","label":"Variedade"}, {"id":"i6","label":"Site fácil"},
{"id":"i7","label":"Pontos"}, {"id":"i8","label":"Sustentabilidade"} ],
"itemsPerTask": 4, "tasksPerRespondent": 6, "designVersions": 20, "seed": 7,
"bestLabel":"Mais importante", "worstLabel":"Menos importante"
} ] },
"blocks": [ { "id":"B_md", "pages": [
{ "elements":[ {"id":"MD1","type":"maxdiff_task","text":"Mais e menos importante?","exerciseId":"M1","taskIndex":0} ] }
// ... uma página por tarefa
] } ]
}
```
### 11.3 Preço — Van Westendorp
Quatro perguntas `numeric` com o mesmo `pricingGroup` e um `pricingRole` cada:
`too_cheap`, `cheap`, `expensive`, `too_expensive`.
```jsonc
{ "id":"vw1","type":"numeric","text":"A que preço seria BARATO DEMAIS, a ponto de duvidar da qualidade?","pricingGroup":"g1","pricingRole":"too_cheap" }
{ "id":"vw2","type":"numeric","text":"A que preço seria uma pechincha?","pricingGroup":"g1","pricingRole":"cheap" }
{ "id":"vw3","type":"numeric","text":"A que preço começa a ficar caro?","pricingGroup":"g1","pricingRole":"expensive" }
{ "id":"vw4","type":"numeric","text":"A que preço seria CARO DEMAIS para comprar?","pricingGroup":"g1","pricingRole":"too_expensive" }
```
### 11.4 Preço — Gabor-Granger
Uma `single_choice` sim/não por preço, com `pricingMethod`, `pricingGroup` e `price`. O "sim"
tem `id` `"yes"`.
```jsonc
{ "id":"gg10","type":"single_choice","text":"Você compraria por R$ 10?",
"pricingMethod":"gabor_granger","pricingGroup":"g1","price":10,
"options":[{"id":"yes","label":"Sim"},{"id":"no","label":"Não"}] }
```
### 11.5 Kano
Por funcionalidade, **duas** `single_choice` na escala de 5 pontos (ids `"0"` a `"4"`), com
`kanoGroup`, `kanoFeature`, `kanoFeatureName` e `kanoSide` (`functional` / `dysfunctional`).
```jsonc
{ "id":"k1f","type":"single_choice","text":"Se o produto TIVER brinde, como você se sente?",
"kanoGroup":"g1","kanoFeature":"brinde","kanoFeatureName":"Brinde","kanoSide":"functional",
"options":[{"id":"0","label":"Gosto"},{"id":"1","label":"É o esperado"},{"id":"2","label":"Tanto faz"},{"id":"3","label":"Consigo conviver"},{"id":"4","label":"Não gosto"}] }
{ "id":"k1d","type":"single_choice","text":"Se o produto NÃO tiver brinde, como você se sente?",
"kanoGroup":"g1","kanoFeature":"brinde","kanoFeatureName":"Brinde","kanoSide":"dysfunctional",
"options":[{"id":"0","label":"Gosto"},{"id":"1","label":"É o esperado"},{"id":"2","label":"Tanto faz"},{"id":"3","label":"Consigo conviver"},{"id":"4","label":"Não gosto"}] }
```
---
## 12. O que NÃO usar na importação
Estes falham para quem responde. Os marcados com **(barrado)** o validador já recusa; os
outros passam nele. Use a alternativa.
| Não use | Por quê | Use |
|---|---|---|
| `"type": "text_block"` ou `"type": "image"` **(barrado)** | não aparece, e trava a página | `{"kind":"text"}` e `{"kind":"image"}` |
| `carryForward` na pergunta | a coleta ignora | `displayIf` por opção (10.1) |
| `expression_display` | só enxerga a própria página e grava valor | calculada + `{{calc.x}}` num texto |
| `{"all"}`, `{"any"}` **(barrado)** | quebra quem chega na condição | `and`/`or`, ou `op` |
| fonte do loop dentro do próprio bloco | o bloco some | fonte num bloco anterior |
| grupo de `columnGroups` ou região de `regions` escritos só como texto | o importador recusa | objetos (5.1) |
| matriz sem `columns` nem `scalePreset` **(barrado)** | página trava | declare as colunas |
| `{{...}}` em rótulo de opção/linha/coluna | aparece literal | uma pergunta por item, com o rótulo no enunciado |
| ids genéricos de cota (`c1`, `Q1`) | o contador colide com outros questionários | ids com o nome do estudo |
Nestes tipos, o limite não é cobrado do respondente: `total` de `constant_sum`/`budget_scale`,
`min`/`max` de `numeric_list` e `matrix_numeric`, o N de `rankTopN`, a faixa do `slider` (que já
abre com um valor marcado, então "obrigatória" não tem efeito nele). Se o limite importa, use
`numeric` com `min`/`max`, ou registre em `_pendencias`.
---
## 13. Códigos de erro do validador (e a correção)
| Código | Significa | Correção |
|---|---|---|
| `não entendi a condição perto de '…'` | sintaxe de `if` inválida | só `== != > >= < <= and or not ( ) count()` |
| `LOGIC_FORWARD_REFERENCE` | condição olha pergunta que ainda não apareceu | a pergunta citada vem **antes** |
| `LOGIC_UNKNOWN_QUESTION` | condição ou fórmula cita pergunta inexistente | confira o `id` (sorteio é `{var.x}`) |
| `CONDITION_MALFORMED` | condição que não é folha nem grupo (`{"all"}`, `"op": "AND"`) | forma curta (6.1) ou completa (6.2), `op` em minúsculas |
| `LOGIC_UNKNOWN_OPTION` | id de opção inexistente na condição | dê `id` fixo à opção e use o mesmo |
| `LOGIC_UNKNOWN_VARIABLE` | variável não declarada | declare em `variables` |
| `LOGIC_UNKNOWN_OPERATOR` | operador que não existe | lista da 6.2 |
| `UNKNOWN_QUESTION_TYPE` | `type` fora do catálogo | seção 4 |
| `ELEMENT_AS_QUESTION` | `"type": "text_block"` ou `"type": "image"` numa pergunta | `{"kind":"text"}` ou `{"kind":"image"}` |
| `MATRIX_WITHOUT_COLUMNS` / `MATRIX_WITHOUT_ROWS` | matriz sem colunas ou sem linhas | declare as duas listas |
| `FLOW_MALFORMED` / `FLOW_UNKNOWN_BLOCK` | nó do `flow` sem a chave de que precisa, ou bloco que não existe | 7 |
| `QUESTION_TYPE_WIP` (aviso) | tipo que ainda não roda | troque por um da seção 4 |
| `CHOICE_WITHOUT_OPTIONS` | pergunta de escolha sem opções | declare `options` |
| `DUP_QUESTION_ID` | dois elementos com o mesmo `id` | ids únicos |
| `UNKNOWN_ENDING` / `UNKNOWN_SKIP_TARGET` | aponta para encerramento/página/bloco que não existe | crie ou corrija o id |
| `EXPR_INVALID` | fórmula inválida, ou calculada sem fórmula | referências entre chaves `{id}` |
| `EXPR_UNDECLARED_VAR` (aviso) | fórmula cita `{var.x}` não declarada | declare em `variables`, ou confirme que vem na URL |
| `EXPR_UNKNOWN_OPTION` | rótulo citado na fórmula não existe | copie o rótulo exato |
| `CF_CYCLE` | calculadas em ciclo | quebre o ciclo |
| `VAR_NAME_INVALID` / `VAR_NAME_RESERVED` / `VAR_NAME_DUPLICATE` | nome de variável ruim | 8.1 |
| `VAR_NAME_FROM_URL` (aviso) | variável de painel declarada à toa | não declare `rid`, `pid`, `gid`, `psid`, `utm_*` |
| `FLOW_UNDECLARED_VAR` (aviso) | `set_variables` com variável não declarada | declare em `variables` |
| `DRAW_UNKNOWN_ENDING` | `whenEmpty: screenout` sem encerramento | `whenEmptyEndingId` + o encerramento |
| `DRAW_TOPN_MISSING` | `ranked_top_n` sem `topN` | declare `topN` |
| `QUOTA_SEM_CORTE` (aviso) | cota sem `quota_check` no fluxo | ponha o corte depois do perfil |
| `QUOTA_FORWARD_REFERENCE` | corte antes da pergunta da cota | mova o `quota_check` para depois |
| `LOOP_SINGLE_PASS` (aviso) | loop sobre resposta única com `selected` | `"pool":"all"` |
| `PIPE_UNKNOWN_REF` (aviso) | `{{ref}}` não existe | corrija a referência |
| `TRANSLATION_MISSING` (aviso) | falta texto num idioma | complete |
| `EMPTY_QUESTION_TEXT` / `EMPTY_OPTION_LABEL` / `DUPLICATE_OPTION` (aviso) | enunciado ou opção sem texto, opção repetida | escreva o texto; ids e rótulos únicos |
| `EMPTY_PAGE` (aviso) | página sem nada, que a coleta pula | tire a página, ou ponha as perguntas nela |
| `VALIDATION_KEY_INERT` (aviso) | chave de `validation` que o motor não lê (`numericMin`, `pattern`…) | o recado diz onde ela mora |
| `RANDOMIZATION_STRATEGY_INVALID` | `optionRandomization`, `rowRandomization` ou `columnRandomization` com estratégia que a coleta não conhece, ou `optionRandomization` que não é objeto: a página quebra na frente de quem responde | use `shuffle`, `rotation`, `reverse_random`, `alphabetical`, `subset_n`, `shuffle_groups` ou `groups_and_items` |
| `RANDOMIZATION_SHUFFLES_COLUMNS` (aviso) | matriz com `optionRandomization` e sem `columnRandomization`: as colunas (a escala) também saem em ordem sorteada | `columnRandomization: "as_is"` para sortear só as linhas |
| `RANDOMIZATION_INERT` (aviso) | `randomization` numa pergunta: a coleta não lê, e a ordem sai fixa | `optionRandomization` (na pergunta); `randomization` só vale no bloco, para a ordem das páginas |
| `ATTENTION_CHECK_SEM_GABARITO` (aviso) | armadilha de atenção sem `correctOptionId`, ou com um que não é alternativa: nunca conta na pontuação de qualidade | `correctOptionId` com o id da alternativa certa |
| `OPTION_KEY_INERT` (aviso) | campo em alternativa, linha ou coluna que ninguém lê (ex.: `anchor`, `value`): fica gravado e não faz nada | o recado diz o campo certo — `fixedPosition`/`allowText`/`exclusive` para posição, `code` para o código |
---
## 14. Exemplo completo
Estudo de café: apresentação → triagem (idade, profissão, marcas conhecidas) → perfil com cota
→ marca usada (herança) → avaliação da marca sorteada → NPS com motivo condicional.
```json
{
"meta": { "title": "Hábitos de café 2026", "screenoutMode": "immediate" },
"variables": [ {"name":"canal","type":"text","defaultValue":"site","exportable":true} ],
"draws": [ { "name":"marca", "source":{"questionId":"conhece"},
"exclude":"['outro','nenhuma']", "balance":true,
"whenEmpty":"screenout", "whenEmptyEndingId":"filtro", "exportable":true } ],
"blocks": [
{ "id":"B_intro", "pages":[ { "id":"P_intro", "elements":[
{ "kind":"text", "id":"T_intro",
"html":"Olá!Esta pesquisa sobre café leva cerca de 5 minutos.
" } ] } ] },
{ "id":"B_filtro", "title":"Antes de começar", "pages":[
{ "id":"P_idade", "elements":[
{ "id":"idade", "type":"numeric", "text":"Qual é a sua idade?", "min":0, "max":120,
"skipTo":[ {"if":"idade < 18", "target":{"kind":"ending","endingId":"filtro"}} ] },
{ "id":"setor", "type":"multi_choice", "text":"Você ou alguém da sua casa trabalha em alguma destas áreas?",
"options":[ {"id":"pesquisa","label":"Pesquisa de mercado"},
{"id":"cafe","label":"Indústria de café"},
{"id":"nenhum","label":"Nenhuma destas","exclusive":true} ],
"skipTo":[ {"if":"setor == 'pesquisa' or setor == 'cafe'",
"target":{"kind":"ending","endingId":"filtro"}} ] } ] },
{ "id":"P_conhece", "elements":[
{ "id":"conhece", "type":"multi_choice", "text":"Quais destas marcas de café você conhece?",
"optionRandomization":{"strategy":"shuffle"},
"options":[ {"id":"pilao","label":"Pilão"}, {"id":"melitta","label":"Melitta"},
{"id":"tres","label":"3 Corações"}, {"id":"nescafe","label":"Nescafé"},
{"id":"outro","label":"Outra","allowText":true},
{"id":"nenhuma","label":"Não conheço nenhuma","exclusive":true} ],
"skipTo":[ {"if":"conhece == 'nenhuma'", "target":{"kind":"ending","endingId":"filtro"}} ] } ] } ] },
{ "id":"B_perfil", "title":"Sobre você", "pages":[ { "id":"P_perfil", "elements":[
{ "id":"sexo", "type":"single_choice", "text":"Com qual gênero você se identifica?",
"options":[ {"id":"f","label":"Feminino"}, {"id":"m","label":"Masculino"},
{"id":"outro_g","label":"Outro"}, {"id":"na","label":"Prefiro não responder"} ] },
{ "id":"regiao", "type":"dropdown", "text":"Em qual região você mora?",
"options":[ {"id":"se","label":"Sudeste"}, {"id":"s","label":"Sul"}, {"id":"ne","label":"Nordeste"},
{"id":"n","label":"Norte"}, {"id":"co","label":"Centro-Oeste"} ] } ] } ] },
{ "id":"B_main", "title":"Seu café", "pages":[
{ "id":"P_usa", "elements":[
{ "id":"usa", "type":"single_choice", "text":"Das marcas que você conhece, qual usa mais?",
"options":[ {"id":"pilao","label":"Pilão","displayIf":"conhece == 'pilao'"},
{"id":"melitta","label":"Melitta","displayIf":"conhece == 'melitta'"},
{"id":"tres","label":"3 Corações","displayIf":"conhece == 'tres'"},
{"id":"nescafe","label":"Nescafé","displayIf":"conhece == 'nescafe'"},
{"id":"outra_u","label":"Outra marca"} ] } ] },
{ "id":"P_aval", "elements":[
{ "id":"aval", "type":"matrix_single", "text":"Sobre a marca {{draw.marca}}, o quanto você concorda?",
"description":"Marque uma resposta por linha.",
"scalePreset":"likert5_agree", "rowRandomization":{"strategy":"shuffle"},
"rows":[ {"id":"r_sabor","label":"Tem um sabor que eu gosto"},
{"id":"r_preco","label":"Tem um preço justo"},
{"id":"r_confia","label":"É uma marca em que eu confio"} ] } ] },
{ "id":"P_nps", "elements":[
{ "id":"nps", "type":"nps", "text":"De 0 a 10, quanto você recomendaria {{draw.marca}} a um amigo?",
"leftLabel":"Nada provável", "rightLabel":"Muito provável" },
{ "id":"motivo", "type":"text_long", "required":false, "text":"O que faria você dar uma nota maior?",
"displayIf":{"if":"nps <= 6"} } ] } ] }
],
"_quotas": [ { "id":"cafe2026_sexo", "name":"Sexo", "cells":[
{ "id":"cafe2026_sexo_f", "name":"Feminino", "target":150,
"condition":{"source":{"kind":"question","questionId":"sexo"},"operator":"selected","operand":"f"} },
{ "id":"cafe2026_sexo_m", "name":"Masculino", "target":150,
"condition":{"source":{"kind":"question","questionId":"sexo"},"operator":"selected","operand":"m"} } ] } ],
"flow": [
{ "kind":"block", "blockId":"B_intro" },
{ "kind":"block", "blockId":"B_filtro" },
{ "kind":"block", "blockId":"B_perfil" },
{ "kind":"quota_check", "quotaId":"cafe2026_sexo" },
{ "kind":"block", "blockId":"B_main" },
{ "kind":"ending", "endingId":"fim" }
],
"endings": [
{ "id":"fim", "status":"complete", "label":"Fim", "message":"Obrigado por participar!" },
{ "id":"filtro", "status":"terminated", "label":"Não elegível",
"message":"Obrigado! Neste momento a pesquisa não segue para o seu perfil." },
{ "id":"cheia", "status":"overquota", "label":"Cota cheia",
"message":"Obrigado! Já temos respostas suficientes do seu perfil." }
],
"_pendencias": []
}
```
---
## 15. Checklist antes de entregar
- [ ] `meta.screenoutMode` é `"immediate"` (ou ausente, que dá no mesmo).
- [ ] Todo `type` está na seção 4, e nada da seção 12 foi usado.
- [ ] Toda pergunta, opção, linha e coluna citada em lógica tem `id` fixo, sem acento, hífen ou ponto.
- [ ] Nenhuma condição olha para pergunta que vem depois dela.
- [ ] Toda célula de cota tem id com o nome do estudo.
- [ ] Todo `endingId`, `pageId` e `blockId` citado existe; a triagem aponta para um encerramento `terminated`.
- [ ] Quem tem menos de 18 anos é encerrado, se houver pergunta de idade.
- [ ] Marcas de programação foram tiradas dos enunciados; "Outro" tem `allowText`, "Nenhuma" tem `exclusive`.
- [ ] O que não coube no USL está em `_pendencias`.