JSON

Preencha a ficha e veja a máquina escrevê-la

É como a ficha de cadastro de uma recepção: linhas impressas (o nome do campo, que nunca muda) e o que você escreve ao lado (o valor, que muda a cada pessoa). Tem uma linha onde cabe mais de uma coisa, e um quadrinho separado para o endereço. Preencha os campos da ficha.

O nome do campo fica à esquerda dos dois pontos, o valor à direita. E repare: o nome tem aspas, a idade não.

Quase toda linha da ficha é de um destes cinco tipos

Num formulário impresso, nem todo espaço é igual: tem o de escrever o nome, o de valor em reais, o de marcar sim ou não. O JSON separa do mesmo jeito. Você não precisa decorar os nomes em inglês que a ferramenta (o programa de automação onde você vê o JSON) mostra. Precisa reconhecê-los quando aparecerem, e saber que o primeiro é palavra e o segundo é quantidade. Clique em cada um.

A única regra: eu somaria dois desses?

É a mesma diferença entre o ramal e o saldo: os dois são números, mas só um entra na soma do mês. CPF, CEP, telefone e número do pedido são feitos de algarismos, e ninguém soma dois deles: são etiqueta, e etiqueta é palavra. Idade, preço e dias de atraso, somados, significam alguma coisa: são quantidade. O computador não consegue decidir isso sozinho; quem decide é você, pelo uso. Classifique os oito.

Somar duas palavras cola uma na outra

É o que acontece quando a planilha recebe valores colados como texto: a soma do rodapé sai errada, e ninguém percebe de cara. Se um sistema manda o valor como palavra, o próximo passo (a etapa seguinte da automação) não faz conta: junta os pedaços. E a comparação "maior que 18" nem começa. Mude os valores e o tipo de cada um.

A mensagem da comparação é a que as ferramentas mostram de verdade, em inglês: '32' is a string but was expecting a number, ou seja, "esperava uma quantidade e recebeu uma palavra". A saída é converter antes, e a conversão é um passo, não um palpite.

Para chegar num valor, vá de fora para dentro, separando por ponto

Pense no endereço de uma correspondência interna: prédio, andar, sala, mesa. Cada nível fica dentro do anterior, e se faltar um, a carta não chega. Um pedido de uma loja tem o cliente, e o cliente tem o endereço. Os itens são uma lista, e cada item é uma ficha. Abra e feche as partes, e clique num valor para ver o caminho até ele. É a mesma lógica de pasta dentro de pasta no computador.

Na lista, a contagem começa do zero: o primeiro item é itens[0]. E se o quadrinho de dentro não existir num cadastro, o caminho inteiro quebra naquele ponto.

Três fichas numa lista, e o passo que roda três vezes

É a mala direta do editor de texto: uma carta-modelo, uma planilha com 50 nomes, e sai uma carta para cada linha, sem ninguém mandar repetir. Uma planilha de 50 linhas chega ao passo seguinte como uma lista de 50 fichas, e o passo roda uma vez para cada uma, sozinho. Mesmo quando aparece "1 item", ele está dentro de uma lista. Troque a visão e rode o passo.

A tabela arruma para ficar bonito, e nesse arrumar as aspas e o quadrinho de dentro somem. Quando algo der errado, olhe o JSON.

Rodar uma vez por ficha é ótimo para escrever. É péssimo quando o passo seguinte é enviar: três fichas viram três mensagens para o mesmo gerente, e uma planilha de 300 linhas vira 300 e-mails. Antes de enviar, junte as fichas de volta numa lista só. Compare.

Quando algo sai repetido ou some, a primeira pergunta é quantos itens chegaram neste passo? Se um passo não deve repetir de jeito nenhum (mandar o resumo, avisar o gerente), muitas ferramentas têm a opção de rodar uma vez só. Ir um item por vez a ferramenta já faz sozinha; pausa entre um e outro só quando o outro lado limita o ritmo, como em faça um pedido.

Tudo verde, e o resultado errado

É como o boleto pago com o valor errado: o banco aceita, o comprovante sai, e o problema só aparece no fechamento do mês. Erro que aparece é fácil: a ferramenta avisa e você conserta. O caro é o que passa calado: o e-mail vai para quem não devia, o cliente satisfeito cai na lista dos insatisfeitos. Quase sempre é a regra das aspas aparecendo de outro jeito. Abra cada cartão.

Ninguém escreve essa ficha do zero

Funciona como contrato de aluguel: ninguém redige do zero, pede um modelo e confere as cláusulas que importam. Com o JSON, nem quem programa escreve do zero. O que se faz é descrever em português o que você quer guardar, pedir para a IA montar o formato, e conferir a resposta olhando as aspas. Dois pedidos prontos: um para montar, outro para quando a ferramenta recusar. Veja também como escrever pedidos na página Prompt.

1. O que é código (pedido, CPF, CEP, telefone) está entre aspas?
2. O que é quantidade (dias, valores, notas) está sem aspas?
3. Sim e não estão como true e false, e não como "sim" e "não" entre aspas?
4. Os nomes dos campos estão sem acento, sem espaço e sem maiúscula?
5. Cada chave e cada colchete que abriu, fechou?
6. Os nomes dos campos são os mesmos da última vez, letra por letra?

Num fluxo, a IA também pode responder nesta ficha, se você pedir o formato: sem ele vem um parágrafo, que você lê e o passo seguinte não consegue usar. Como chegar a esse formato está em uma linha por vez. Escolheu o nome de uma chave, fique nele: se hoje vem valor e amanhã valor_total, o passo seguinte deixa de achar, sem avisar.

Três ideias

JSON

O formato de ficha que os sistemas usam para trocar informação: nome do campo, dois pontos, valor.

Campo (chave)

O nome da linha, à esquerda dos dois pontos. Não muda de uma ficha para outra.

Valor

O que foi preenchido, à direita dos dois pontos.

Palavra (string)

Texto, sempre entre aspas: nome, cidade, código, telefone.

Quantidade (number)

Número de fazer conta, sem aspas: idade, preço, dias.

Sim ou não (boolean)

Só dois valores, true e false, sem aspas.

Lista (array)

Vários valores numa linha só, entre colchetes. A contagem começa do zero.

Ficha dentro (object)

Um quadrinho com linhas próprias, entre chaves. Chega-se nele com ponto: endereco.cidade.

Vazio (null)

Nada preenchido. Não é zero, e comparado com um número dá sempre falso.

Simplificação didática. As fichas, nomes e pedidos são fictícios. O formato JSON tem mais detalhes do que os mostrados aqui; os cinco tipos e a regra das aspas cobrem o que aparece no dia a dia de quem monta automação. Os nomes em inglês entre parênteses são os que as ferramentas costumam mostrar.