O tipo participa do significado
A RFC 8259 define valores JSON como objetos, arrays, números, textos, booleanos e null. Essa lista não decide automaticamente o tipo certo para cada campo do seu projeto. A equipe que troca os dados precisa documentar o significado esperado. Um número de unidades é uma quantidade; um código de produto pode ser um identificador que usa dígitos como parte da sua escrita.
No exemplo próprio {"codigo":"00125","quantidade":3}, codigo está representado como texto e quantidade como número. As aspas mantêm o identificador escrito com zeros à esquerda. Usar 125 no lugar de "00125" seria uma mudança da representação, e possivelmente do contrato, não uma simples melhoria visual. Antes de converter, confirme como o sistema receptor identifica o item.
Diferencie ausência, zero e resposta negativa
Um campo ausente, um campo com null, um número zero e um booleano false podem representar situações distintas no seu contrato. Por exemplo, uma aplicação pode definir quantidade zero como nenhuma unidade e quantidade null como informação ainda não registrada. Essa distinção é uma escolha explícita do projeto. Ela precisa ser comunicada; o formato JSON sozinho não cria a regra de negócio.
Crie exemplos para cada situação permitida e confira a interpretação das duas partes da integração. Se aprovado pode ser false, não remova o campo apenas porque seu valor parece vazio numa condição genérica do código. Se a omissão é permitida, descreva o comportamento esperado. Um caso pequeno que mostra a diferença evita discussões baseadas em um documento grande com muitos campos não relacionados.
Faça mudanças com um contrato verificável
Para cada campo, anote nome, tipo, unidade quando houver, obrigatoriedade e exemplo. O registro valor: 100 fica mais claro quando você informa se representa reais, centavos ou outra medida escolhida pelo projeto. Não deduza a unidade olhando apenas o tamanho do número. Registre também se uma lista vazia e a ausência da lista produzem o mesmo resultado no sistema de destino.
A ferramenta do Byte Certo pode organizar a leitura do JSON e ajudar a conferir sua sintaxe. A definição e a validação das regras dos campos precisam vir do contrato da integração. Ao alterar um tipo, mantenha um exemplo anterior e outro novo, descrevendo o motivo e quem deve ajustar a leitura. Esse cuidado torna a mudança revisável e reduz a chance de uma conversão automática apagar uma distinção que o processo precisava preservar.