JSON antes da IA: valide sintaxe, encoding e amostra mínima

Um arquivo JSON pode parecer legível e ainda falhar quando entra em uma automação. Uma vírgula sobrando impede a leitura. Um número entre aspas muda o tipo. Duas chaves iguais podem fazer um programa conservar apenas o último valor. Um bloco válido na sintaxe também pode estar incompleto para a tarefa, conter dados desnecessários ou ser grande demais para uma revisão confiável.

Neste guia, você vai preservar o original, confirmar UTF-8 e sintaxe, procurar chaves duplicadas, revisar tipos e campos obrigatórios, recortar uma amostra mínima e registrar o hash antes de pedir análise a uma IA. O resultado é um arquivo menor, reproduzível e acompanhado de critérios claros, sem transformar o modelo em validador exclusivo.

Resultado esperado

Ao final, você terá o JSON original preservado, uma cópia de trabalho em UTF-8, evidência de que a sintaxe foi analisada por uma ferramenta local, uma checagem separada para chaves duplicadas, uma lista de campos e tipos esperados, uma amostra sem dados desnecessários e o SHA-256 da versão enviada.

Pré-requisitos

• um arquivo JSON cuja origem e finalidade sejam conhecidas;
• permissão para processar e compartilhar os dados;
• PowerShell disponível no Windows;
• opcionalmente, Python 3 para uma segunda validação e detecção de chaves duplicadas;
• uma pasta de trabalho separada do arquivo original;
• uma descrição dos campos necessários para a análise.

Os exemplos usam dados.json. Substitua pelo caminho real e mantenha aspas ao redor de caminhos com espaços. Não execute comandos recebidos dentro do JSON. O arquivo é dado, não script.

O que JSON válido realmente significa

A RFC 8259 define que um valor JSON pode ser objeto, array, número, string, booleano ou null. Nomes de propriedades são strings. Os literais true, false e null usam letras minúsculas. Comentários, vírgula depois do último item e chaves sem aspas não fazem parte da gramática padrão.

A mesma especificação recomenda nomes únicos dentro de cada objeto. Quando uma chave se repete, programas diferentes podem manter apenas o último valor, rejeitar o documento ou expor todas as ocorrências. Por isso, “abriu sem erro” não basta quando perda silenciosa de campo é relevante.

Para troca entre sistemas, a RFC exige UTF-8. Também observa que analisadores podem impor limites de tamanho, profundidade, comprimento de string e precisão numérica. Um arquivo válido pode, portanto, exceder o que uma ferramenta, API ou modelo aceita.

Passo 1: preserve o original e registre a origem

Copie o arquivo para uma pasta de trabalho. Não formate, corrija ou reduza a única versão recebida. Registre quem ou qual sistema gerou o JSON, quando ele foi exportado, qual intervalo de dados representa e qual tarefa será feita.

Calcule o hash do original no PowerShell:

Get-FileHash -LiteralPath ".\dados.json" -Algorithm SHA256

O hash não diz que os dados estão corretos. Ele identifica os bytes daquela versão. Se o arquivo mudar depois, o novo hash ajuda a separar correção legítima de troca acidental.

Passo 2: faça a primeira leitura como texto

Antes de analisar a estrutura, procure sinais de que o conteúdo não deveria sair do ambiente: tokens, senhas, chaves de API, cookies, documentos pessoais, endereços, prontuários, dados financeiros, segredos comerciais e identificadores de clientes.

Veja também o começo e o fim do arquivo sem imprimir tudo no terminal:

Get-Content -LiteralPath ".\dados.json" -TotalCount 20
Get-Content -LiteralPath ".\dados.json" -Tail 20

Essa inspeção pode revelar HTML no lugar de JSON, mensagem de erro salva como arquivo, conteúdo truncado ou registros que não pertencem ao escopo. Evite colar o arquivo inteiro em uma conversa apenas para descobrir o formato.

Passo 3: valide a sintaxe no PowerShell

Leia o documento inteiro com -Raw e peça ao PowerShell para convertê-lo:

$raw = Get-Content -LiteralPath ".\dados.json" -Raw -Encoding UTF8
$obj = $raw | ConvertFrom-Json -ErrorAction Stop
"JSON aceito pelo PowerShell"

A documentação do ConvertFrom-Json explica que -Raw devolve o arquivo como uma única string para conversão. Se houver erro, anote linha e coluna, corrija somente na cópia e repita.

Não salve imediatamente o objeto de volta com ConvertTo-Json. A ida e volta pode alterar representação de datas, profundidade, ordem visível ou arrays com um único elemento, dependendo da versão e dos parâmetros. Primeiro entenda o arquivo e preserve o original.

Passo 4: confirme com um segundo analisador

Se Python 3 estiver instalado, use o módulo padrão json.tool:

python -m json.tool ".\dados.json"

O comando valida e imprime uma versão formatada. A documentação oficial do Python mostra que entradas inválidas retornam uma mensagem com a posição do problema.

Dois analisadores não provam a semântica, mas ajudam a separar uma particularidade de uma ferramenta de um erro básico de sintaxe. Se PowerShell e Python discordarem, não envie o arquivo como se estivesse resolvido. Registre versões, mensagem completa e o menor trecho que reproduz a diferença.

Passo 5: rejeite chaves duplicadas

PowerShell e várias bibliotecas podem conservar somente uma ocorrência quando o mesmo nome aparece mais de uma vez. Para uma checagem explícita com Python, salve o código abaixo como validar_json_sem_duplicadas.py na pasta de trabalho:

import json
import sys

def reject_duplicates(pairs):
    result = {}
    for key, value in pairs:
        if key in result:
            raise ValueError(f"chave duplicada: {key}")
        result[key] = value
    return result

with open(sys.argv[1], encoding="utf-8") as source:
    json.load(source, object_pairs_hook=reject_duplicates)

print("JSON válido e sem chaves duplicadas")

Execute sem modificar o arquivo:

python ".\validar_json_sem_duplicadas.py" ".\dados.json"

Se aparecer uma chave duplicada, volte ao sistema que gerou o documento. Apagar uma ocorrência por conta própria pode esconder qual valor era o correto. Quando a correção manual for inevitável, registre o antes, o depois e a regra aplicada.

Passo 6: revise tipos, ausências e valores vazios

Sintaxe válida não distingue um identificador "00123" de um número 123. Também não diz se null, string vazia e campo ausente significam a mesma coisa para o processo. Monte uma tabela mínima:

Campo	Tipo esperado	Pode faltar?	Amostra
id_pedido	string	não	“00123”
valor	número	não	149.90
observacao	string ou null	sim	null
itens	array	não	[]

Confira datas e horários como texto, incluindo fuso quando ele importa. Revise números grandes, moeda, separador decimal, zeros à esquerda e identificadores que parecem números. A RFC alerta que implementações podem aplicar limites diferentes à precisão numérica.

Passo 7: use JSON Schema quando houver contrato

Se o arquivo alimenta um processo repetido, descreva a estrutura em JSON Schema. Um esquema pode declarar objeto, propriedades, tipos, campos obrigatórios e se chaves adicionais são aceitas.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id_pedido": { "type": "string" },
    "valor": { "type": "number", "minimum": 0 },
    "itens": { "type": "array" }
  },
  "required": ["id_pedido", "valor", "itens"],
  "additionalProperties": false
}

A documentação do JSON Schema para objetos ressalta que declarar uma propriedade não a torna obrigatória por padrão. É preciso usar required. additionalProperties também precisa de decisão explícita se campos inesperados devem ser rejeitados.

Escolha um validador compatível com o dialeto declarado e registre sua versão. Uma IA pode ajudar a explicar o esquema, mas a validação deve ser executada por ferramenta própria e repetível.

Passo 8: produza uma amostra mínima

Selecione poucos registros que representem o problema: um caso comum, um com valor ausente permitido, um com caracteres acentuados, um com array vazio e um caso-limite relevante. Remova campos que não participam da análise.

Substitua identificadores reais por valores fictícios consistentes. Não basta apagar o nome se combinação de endereço, telefone, código interno e observação ainda identifica alguém. Preserve a relação necessária, não a identidade.

Valide a amostra novamente com os mesmos comandos. Calcule um novo SHA-256 e dê a ela um nome inequívoco, como pedidos-amostra-sanitizada-2026-09-04.json.

Passo 9: formule o pedido com critérios verificáveis

Explique à IA que o arquivo já passou por validação sintática, mas que os resultados precisam ser conferidos. Declare o objetivo, os campos que podem ser usados e os que devem ser ignorados. Peça para não preencher ausências, não converter identificadores em números e sinalizar qualquer registro que não siga o contrato informado.

Defina a saída, por exemplo uma tabela com id_pedido, problema observado, evidência no JSON e ação sugerida. Depois compare cada conclusão com o arquivo da amostra. Se o modelo citar campo inexistente ou inferir valor ausente, marque como erro e ajuste o processo.

Teste o resultado esperado antes do envio

Abra a amostra em uma ferramenta local e responda manualmente uma ou duas perguntas que depois serão feitas à IA. Conte os registros, localize um identificador conhecido e confirme um total simples. Esse gabarito pequeno permite verificar se o modelo leu a estrutura certa, preservou tipos e não ignorou itens aninhados.

Se a amostra contém quatro pedidos e sete itens, registre esses dois números antes do upload. A resposta não precisa reproduzir todo o arquivo, mas deve ser compatível com o gabarito. Quando divergir, investigue se o problema veio da amostra, do prompt, da conversão, do limite de contexto ou da interpretação do modelo. Não corrija a saída por intuição.

Erros comuns

• confiar apenas porque o editor coloriu o JSON;
• usar um formatador online com dados que não podem sair do ambiente;
• corrigir o único original;
• ignorar chaves duplicadas porque o parser não reclamou;
• tratar identificador com zeros à esquerda como número;
• confundir null, campo ausente e string vazia;
• supor que um esquema valida campos não marcados como obrigatórios;
• enviar o arquivo completo quando cinco registros reproduzem o problema;
• aceitar a análise da IA sem conferir os registros citados.

Checklist antes de enviar

• O original foi preservado e teve SHA-256 registrado?
• A origem, data e finalidade do arquivo estão documentadas?
• Segredos e dados fora do escopo foram removidos da cópia?
• PowerShell aceitou a sintaxe com ConvertFrom-Json?
• Um segundo analisador confirmou o resultado?
• Chaves duplicadas foram verificadas separadamente?
• Tipos, campos ausentes, null e strings vazias foram revisados?
• O esquema declara propriedades obrigatórias e extras?
• A amostra conserva os casos-limite sem expor identidades?
• O hash da versão enviada foi registrado?
• A resposta será comparada com o JSON, campo por campo?

O que este método não garante

Ele não certifica a origem dos dados, não confirma que os valores são verdadeiros, não substitui testes do sistema consumidor e não elimina obrigações de privacidade ou segurança. Também não garante que duas linguagens tratarão números, datas, ordem de propriedades ou Unicode exatamente da mesma forma.

Para integrações críticas, mantenha testes automatizados, esquema versionado, exemplos válidos e inválidos e validação no ponto de entrada. A IA pode ajudar a encontrar padrões e explicar falhas, mas o contrato executável continua sendo a fonte de controle.

Fontes oficiais consultadas em 4 de setembro de 2026

• RFC Editor: RFC 8259, The JavaScript Object Notation Data Interchange Format.
• Microsoft Learn: ConvertFrom-Json.
• Python: módulo json e interface json.tool.
• JSON Schema: objetos, propriedades e campos obrigatórios.

Leitura complementar

• Como validar um CSV localmente antes de pedir análise a uma IA.
• Como preparar um documento antes de enviar para uma IA.

A imagem de capa é uma ilustração editorial exclusiva do Bastidores da IA. Não é captura de tela, validação executada, esquema real ou resultado de análise.