Como organizar dados em JSON antes de os enviar à IA
Para organizar dados em JSON antes de os enviar à IA, define os campos, escolhe tipos consistentes e estabelece como representar informação em falta. Depois, verifica o formato e compara os valores com a fonte. Este guia acompanha um exemplo de tarefas de reunião, desde as notas até à preparação do pedido.
O que deves decidir antes de criar o JSON?
Começa pela operação que queres fazer com os dados. Se pretendes identificar tarefas por confirmar, precisas de distinguir a ação, o responsável, o prazo e a origem da informação. Decide o significado de cada campo antes de pedir à IA que preencha uma estrutura aparentemente completa.
Imagina uma nota fictícia: «Ficou decidido rever o documento de apresentação. Ainda falta escolher quem faz a revisão e combinar a data.» Tens uma ação acordada e duas informações em falta. Se preencheres o responsável com o nome de quem falou mais, alteras o conteúdo da reunião.
Escreve primeiro uma pequena definição do trabalho: preparar tarefas para revisão humana, mantendo explícitas as lacunas. Nesta fase, criar automaticamente cartões numa ferramenta de gestão seria uma decisão adicional. O exemplo serve para aprender a estruturar informação, sem enviar mensagens nem atribuir trabalho a pessoas reais.
O mesmo raciocínio aplica-se a pedidos comerciais ou fichas de produtos. Um campo só deve existir se tiver significado e utilidade no processo seguinte. Se estás a começar por reuniões, o guia para transformar reuniões em tarefas com IA ajuda-te a separar decisões, propostas e perguntas antes desta organização técnica.
Como representar uma tarefa num exemplo simples?
Usa um objeto para reunir os dados de uma tarefa e uma lista quando houver várias tarefas. Mantém os nomes dos campos iguais entre registos. O exemplo seguinte é fictício e deixa responsável e prazo sem valor conhecido, em vez de completar essas lacunas com uma sugestão do modelo.
{"reuniao_id": "R-EXEMPLO", "tarefas": [{"tarefa_id": "T-01", "descricao": "Rever o documento de apresentação", "responsavel": null, "prazo": null, "estado": "acao_confirmada", "referencia": "nota-01"}]}
Podes copiar esta linha para um ficheiro local de teste com extensão .json. A referência «nota-01» é um identificador inventado para este exercício, associado à frase da secção anterior. Num processo real, teria de apontar para uma passagem que conseguisses consultar.
JSON usa pares de nomes e valores, objetos entre chavetas e listas entre parênteses retos. Os nomes e os valores de texto usam aspas duplas; números, booleanos e null têm representação própria. Evita nomes repetidos no mesmo objeto, porque diferentes leitores podem tratá-los de forma diferente. Estas regras estão definidas na especificação JSON, RFC 8259.
A ordem visual dos campos foi escolhida para facilitar a leitura do exemplo. Quando ligares uma aplicação, faz o mapeamento pelo nome do campo. Assim, mudar a apresentação do registo não passa a significar trocar o responsável pelo prazo.
Que regras deves escrever para cada campo?
Cria uma descrição curta dos campos que o processo recebe, incluindo o tipo de valor e as situações em que pode faltar informação. Esta descrição funciona como um acordo entre quem prepara os dados e quem os utiliza. Testa-a com exemplos concretos antes de acrescentares dezenas de propriedades.
| Campo | Regra deste exercício | Pergunta de revisão |
|---|---|---|
| tarefa_id | Identificador estável atribuído pelo processo | Consigo reconhecer a mesma tarefa noutra execução? |
| descricao | Texto com a ação acordada | Mantém o sentido da nota original? |
| responsavel | Nome confirmado ou null | Existe uma atribuição explícita na fonte? |
| prazo | Data confirmada ou null | A data foi combinada ou apenas sugerida? |
| estado | Valor de uma lista definida pela equipa | Distingue uma ação confirmada de uma proposta? |
| referencia | Identificador da passagem de origem | Consigo voltar à informação usada? |
Estas regras são uma proposta para o exercício. No teu negócio, podes precisar de distinguir uma pessoa de uma equipa, ou uma data de uma janela temporal. Escreve essa diferença antes de escolher os nomes definitivos. Um campo chamado «responsável» não esclarece, por si só, se aceita várias pessoas.
Evita acrescentar prioridade, esforço estimado e impacto financeiro só porque cabem no JSON. Cada novo campo exige uma origem ou um método de cálculo. Se queres pedir uma estimativa à IA, guarda-a como estimativa e indica os pressupostos, separada do que foi efetivamente decidido.
Como lidar com null, campos ausentes e listas vazias?
Define o significado de informação em falta para o teu processo e aplica-o de forma consistente. Neste exercício, null significa que o campo existe, mas o valor ainda não está confirmado. Uma lista de tarefas vazia tem outra interpretação, que também precisa de ser decidida e testada pela equipa.
Imagina que o processamento de uma nota terminou e não encontrou ações acordadas. Podes representar esse resultado com uma lista vazia, acompanhada de um estado de processamento concluído. Se a leitura da nota falhou, uma lista vazia sozinha esconderia o problema. Guarda a falha separadamente e impede que pareça uma reunião sem tarefas.
Em JSON Schema, exigir a presença de uma propriedade e permitir que o seu valor seja null são decisões distintas. A palavra-chave required estabelece campos obrigatórios; declarar propriedades não as torna automaticamente obrigatórias. A documentação de objetos do JSON Schema explica esta distinção e o controlo de propriedades adicionais.
No exemplo, mantém responsável e prazo presentes para que a revisão encontre as lacunas facilmente. Escrever «por confirmar» pode ser útil numa interface, mas decide se esse texto pertence ao dado armazenado ou apenas à apresentação. Não alternes entre as duas soluções consoante a resposta do modelo.
O que deves validar antes de enviar os dados à IA?
Faz três verificações: leitura do formato, cumprimento das regras dos campos e correspondência com a fonte. Uma estrutura aceite por um leitor de JSON pode conter um prazo inventado ou uma tarefa duplicada. Prepara um resultado esperado para cada verificação, para conseguires localizar o problema quando alguma falhar.
Na primeira passagem, confirma que o conteúdo é interpretado como JSON. Uma vírgula final indevida, aspas tipográficas ou comentários introduzidos dentro do ficheiro podem impedir a leitura. Guarda as explicações fora do exemplo que a aplicação vai interpretar. A validação deve usar o conteúdo exato que pretendes enviar.
Na segunda, verifica as regras que definiste: os campos necessários estão presentes, os tipos são aceites e o estado pertence à lista acordada. Na terceira, regressa à nota original. A descrição preserva a ação? O responsável foi confirmado? A referência aponta para a passagem certa?
Regista o motivo de rejeição, como «prazo preenchido sem evidência», em vez de uma mensagem genérica de erro. Isso permite corrigir a etapa adequada. Se precisas de preparar as fontes antes desta revisão, começa por organizar documentos para obter melhores respostas de IA.
Como evitar confundir uma lista com vários registos no n8n?
Observa os dados que entram e saem de cada etapa antes de criares tarefas noutra ferramenta. Uma reunião pode chegar como um único item com uma lista interna de ações. Confirma se o passo seguinte recebe essa lista inteira ou cada ação separadamente, de acordo com o resultado pretendido.
A documentação do n8n descreve dados organizados em itens, normalmente com uma propriedade json. Muitos nós processam os itens recebidos individualmente, mas uma lista dentro de um item continua a exigir atenção à estrutura. Consulta a estrutura de dados do n8n e o comportamento do nó concreto que estás a usar.
No exercício, prepara uma reunião com duas tarefas diferentes. O resultado desejado da separação são dois registos de tarefa, ambos com o identificador da reunião. Depois prepara uma reunião sem tarefas. A revisão deve confirmar que não apareceu um cartão vazio para representar essa ausência.
Acrescenta ainda um caso em que a mesma ação aparece repetida em duas passagens. Decide como reconhecer a duplicação antes da criação dos cartões. A posição na lista pode mudar entre execuções, por isso não a uses como única identidade de uma tarefa. Mantém uma forma de voltar ao registo de origem.
Como preparar o pedido à IA sem perder o contexto?
Envia os dados acompanhados da finalidade, das regras de interpretação e do resultado esperado. Indica claramente o que a IA pode transformar e o que deve preservar. Para este exercício, pede uma revisão das lacunas e das inconsistências, mantendo identificadores, referências e informação não confirmada tal como foram recebidos.
Um pedido possível seria: «Analisa estas tarefas para preparar uma revisão humana. Identifica campos por confirmar e contradições entre descrição e estado. Não atribuas responsáveis nem datas. Devolve observações associadas ao tarefa_id e explica que informação falta para resolver cada caso.» Este texto é um ponto de partida para testares.
Se a IA tiver de consultar a passagem original, inclui essa passagem ou disponibiliza um acesso apropriado. O identificador «nota-01», isolado, não contém o texto da nota. Um erro frequente é pedir verificação factual e entregar apenas o registo já transformado, sem a evidência que permitiria conferi-lo.
Reduz os dados ao que a tarefa precisa. Para rever a estrutura de tarefas, um exemplo fictício pode ser suficiente. Numa utilização real, evita transportar conversas pessoais ou dados de clientes que não contribuam para a análise. A escolha deve acompanhar o objetivo e as condições da ferramenta usada.
Como testar a passagem dos dados entre ferramentas?
Confirma o valor e o tipo que cada ferramenta recebe, sem te limitares ao aspeto do texto apresentado no ecrã. Um campo pode mostrar um conteúdo parecido com JSON e estar guardado como uma única cadeia de texto. Testa a passagem com poucos registos antes de ligares a execução completa.
Abre a saída do passo que prepara os dados e a entrada do passo seguinte. Verifica se consegues aceder diretamente à lista tarefas e ao campo descricao do primeiro elemento. Se precisas de interpretar novamente um texto inteiro, confirma se essa conversão era esperada na integração.
Evita aplicar conversões sucessivas por tentativa. Há campos de ferramentas que esperam um objeto e outros que esperam texto serializado. Segue o contrato desse campo e regista onde ocorre a conversão. O objetivo é conseguir explicar a passagem, incluindo acentos, aspas presentes nas descrições e valores em falta.
Quando houver uma falha, compara a execução concreta com os dados de teste usados na preparação. Um exemplo fixado no editor pode ser diferente do pedido recebido. O guia para desenhar uma automação antes de abrir o n8n ajuda-te a definir entradas, saídas e pontos de verificação.
Que exercício podes fazer para consolidar o processo?
Prepara cinco notas fictícias, define o resultado esperado de cada uma e passa-as pela mesma estrutura. Inclui uma ação completa, uma ação sem responsável, uma proposta não aprovada, uma nota sem tarefas e uma repetição. Compara os resultados antes de considerares o formato pronto para utilização regular.
Na ação completa, confirma que os valores preservam exatamente o que foi combinado. Na ação sem responsável, a lacuna deve continuar visível. Na proposta, verifica que o estado não passou a compromisso. Na nota sem tarefas, distingue processamento concluído de erro. Na repetição, confere a decisão tomada sobre duplicados.
Experimenta também uma alteração deliberada: troca o responsável de uma tarefa por outro nome, mantendo o formato correto. A validação técnica pode aceitar o registo, mas a comparação com a fonte deve assinalar a diferença. Este teste demonstra concretamente por que precisas das três verificações e ajuda a escolher onde colocar a revisão humana.
Noutra cópia, retira o identificador da reunião. Decide se o processo deve rejeitar o registo, pedir informação adicional ou recuperá-la de uma origem conhecida. Não deixes que o modelo invente um identificador só para satisfazer a estrutura. Regista a decisão e o motivo, para que a pessoa que mantém a automação saiba como tratar o mesmo caso no futuro.
Guarda os exemplos e as observações numa pasta de teste, sem dados reais. Quando mudares o pedido à IA ou acrescentares um campo, volta a executar estes casos. Uma melhoria numa descrição pode introduzir uma alteração indesejada no tratamento dos prazos, e os exemplos ajudam-te a detetá-la.
Termina com uma revisão por outra pessoa: entrega as regras e um registo, sem explicação oral. Pede-lhe que identifique o que está confirmado, o que falta saber e onde consultar a fonte. Se surgirem interpretações diferentes, melhora a descrição dos campos antes de aumentares o volume de dados.
Como podes aprender isto no Laboratório da IA?
No Laboratório da IA, podes trabalhar a estrutura dos teus dados, a preparação dos pedidos e a ligação entre etapas de uma automação. Leva um exemplo pequeno e uma dúvida concreta às aulas e aos Zooms semanais de acompanhamento. Assim, consegues discutir o comportamento esperado e a evidência do que aconteceu.
O exercício deste artigo dá-te uma base útil: notas fictícias, um formato definido, casos de teste e uma lista de lacunas. A partir daí, podes desenvolver o teu processo com maior clareza sobre o que a IA interpreta, o que a automação transforma e o que continua a precisar de confirmação.
Referências
As fontes seguintes documentam o formato JSON, a definição de regras para objetos e a organização dos dados no n8n. Foram consultadas em 14 de outubro de 2026. As notas de reunião, os identificadores e os exercícios deste artigo são exemplos editoriais fictícios para praticares o método.
Aprende a construir isto no Lab.
Trabalha o processo com aulas, materiais e acompanhamento. Leva o que estás a construir e esclarece as dúvidas da tua implementação.
- Definir campos e tratar informação em falta sem inventar dados.
- Verificar formato, regras e correspondência com a fonte.
- Praticar dados e automações nas aulas e Zooms semanais do Laboratório.
Aulas semanais para aprender e aplicar. Zooms de acompanhamento semanais para esclarecer dúvidas. Replay e materiais para retomar o trabalho ao teu ritmo.
Entrar no Laboratório da IA