A definição do formulário

O que você precisa saber

• O formulário é um único objeto JSON com as chaves principais listadas abaixo. Todo salvamento envia todas elas.
• Cada pergunta, opção, linha, regra e cálculo tem um id: um UUIDv7 em minúsculas, único no formulário.
• Títulos e descrições são pequenos documentos de texto formatado, não strings. Já os rótulos de opções, linhas e botões são strings simples.
• Imagens e logos são enviados no trulyform, não via MCP. Mantenha os IDs de arquivo que get_form retorna e use null nas perguntas novas. Veja Design e tema.
• Qualquer chave que o formato não define faz o salvamento falhar, seja onde for. Já uma configuração conhecida que o tipo de pergunta não usa é simplesmente ignorada.

Chaves principais

A referência técnica a seguir é gerada a partir do código e está em inglês, como os assistentes de IA a leem.

Um formulário novo, do jeito que create_form retorna:

{
    "schemaVersion": 2,
    "mediaDefaults": {
        "assetId": null,
        "layout": "above",
        "altText": ""
    },
    "welcome": {
        "enabled": true,
        "title": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Boas-vindas!"}]}]},
        "description": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Queremos muito ouvir você."}]}]},
        "button": "Começar"
    },
    "ending": {
        "title": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Obrigado!"}]}]},
        "description": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Sua resposta foi recebida."}]}]}
    },
    "fields": [
        {
            "id": "01990000-0000-7000-8000-000000000001",
            "kind": "short_text",
            "title": {"type":"doc","content":[{"type":"paragraph","content":[]}]},
            "description": {"type":"doc","content":[{"type":"paragraph","content":[]}]},
            "required": false,
            "options": [],
            "rows": [],
            "settings": {"nextButton":"Próxima"},
            "media": {"inherit":true,"assetId":null,"layout":"above"}
        }
    ],
    "theme": {
        "preset": "paper",
        "background": "#ffffff",
        "foreground": "#111827",
        "primary": "#2563eb",
        "buttonText": "#ffffff",
        "font": "Inter",
        "radius": 12,
        "density": "comfortable",
        "logoAssetId": null,
        "backgroundAssetId": null
    },
    "settings": {
        "allowReanswer": true,
        "hiddenFields": [],
        "fillLimit": null,
        "language": "pt-BR"
    },
    "rules": [],
    "calculations": []
}

Identificadores

• Formato: 32 dígitos hexadecimais em minúsculas, em grupos de 8-4-4-4-12. O terceiro grupo começa com 7 (versão 7), e o quarto, com 8, 9, a ou b. Por exemplo: 01990000-0000-7000-8000-000000000001.
• Únicos no formulário, contando perguntas, opções, linhas, regras e cálculos juntos. Duas opções de perguntas diferentes não podem ter o mesmo ID.
• Mantenha os IDs existentes ao editar. Respostas, regras de lógica e referências de resposta apontam para eles; uma pergunta com ID novo é uma pergunta nova.
• IDs novos: gere um UUIDv7 ou chame list_field_types com id_count para receber IDs prontos. A parte de data e hora do UUIDv7 não é verificada. Os IDs desta documentação são exemplos fáceis de ler; confira se nenhum deles repete um ID que já existe no formulário.
• O mutation_id de save_form_draft também é um UUIDv7, novo a cada salvamento.

Perguntas

Cada item de fields é uma pergunta:

O que cada tipo aceita está em Tipos de pergunta.

Texto formatado

Os títulos e as descrições das perguntas, da tela de boas-vindas e da tela final são documentos de texto formatado: um doc com parágrafos, e os parágrafos com texto.

{
    "type": "doc",
    "content": [
        {
            "type": "paragraph",
            "content": [
                { "type": "text", "text": "What is your " },
                { "type": "text", "text": "work", "marks": [{ "type": "bold" }] },
                { "type": "text", "text": " email address?" }
            ]
        }
    ]
}

Uma descrição vazia fica assim: {"type": "doc", "content": [{"type": "paragraph", "content": []}]}.

Text marks: bold, italic, underline, strike, written as "marks": [{"type": "bold"}]. Up to 4 marks per text node and 10,000 characters per text node.

Para ter várias linhas de texto, use vários parágrafos. Não existe formatação de link: para indicar uma página, escreva o endereço como texto, na descrição, por exemplo. Não adicione marcador de obrigatório, como um asterisco: o trulyform já mostra um nas perguntas obrigatórias.

Referências de resposta

Um nó answerToken mostra uma resposta anterior ou o resultado de um cálculo dentro do texto, com um fallback para quando não houver nada a mostrar. Onde os tokens podem aparecer está explicado em Referências de resposta.

Telas de boas-vindas e final

• welcome: {enabled, title, description, button}. Para começar direto na primeira pergunta, defina enabled como false. Se button ficar em branco, aparece o texto padrão.
• ending: {title, description}, mostrada depois da última pergunta.

Configurações do formulário

Tema e imagens

O theme, o mediaDefaults e o media de cada pergunta estão em Design e tema. Via MCP, mantenha os IDs de arquivo exatamente como get_form retorna e use {"inherit": true, "assetId": null, "layout": "above"} nas perguntas novas.