JSON Stringify

O que o escape realmente faz

O stringify analisa o seu JSON, minifica, envolve o resultado em aspas duplas e faz escape de tudo o que terminaria a string antes da hora. Aspas duplas internas viram \", barras invertidas dobram para \\, e os caracteres de controle abaixo de U+0020 viram suas formas curtas \n, \r, \t, \b e \f, ou um escape \u00XX quando não existe forma curta.

Duas coisas ficam de fora de propósito. A barra normal não recebe escape, porque o JSON não exige; às vezes você vê \/ na saída de outras ferramentas, o que é válido mas desnecessário e vem de um velho hábito de esconder a sequência </script> dentro de HTML. Caracteres não ASCII também ficam como estão, em vez de virar escapes \u, então texto acentuado, CJK e emoji continuam legíveis. As duas formas significam a mesma coisa para um parser, e a legível é mais fácil de comparar num diff.

Codificação dupla, e por que ela incomoda

Esta ferramenta existe porque o escape não é idempotente, e normalmente as pessoas descobrem isso no meio da depuração de outra coisa. Faça escape de um documento uma vez e uma aspa vira \". Faça escape do resultado de novo e ela vira \\\", porque a barra invertida que você acabou de acrescentar agora também é um caractere que precisa de escape. Cada passada praticamente dobra as barras invertidas.

Essa é a marca de um payload serializado duas vezes: um campo que deveria conter um objeto contém uma string de JSON, e as aspas aparecem com barras invertidas quando você lê o log. Acontece quando o código chama um serializador sobre um valor que algum framework já serializou, e a correção quase sempre é remover uma das duas chamadas, não acrescentar uma etapa de decodificação.

O unstringify é a ferramenta para desfazer isso. Rode uma vez por camada de codificação e veja as barras invertidas caírem pela metade a cada vez. Quando elas somem e o resultado é analisado como objeto, você descobriu quantas camadas havia.

Quando uma string com escape é o que você precisa

Ao embutir um payload em outro documento JSON, que é como envelopes de webhook, filas de jobs e logs de auditoria costumam carregar um corpo arbitrário. Ao definir uma variável de ambiente com um valor JSON, em que o shell comeria as aspas. Ao colar o corpo de uma requisição num arquivo YAML de um job de CI. Ao escrever uma fixture de teste como literal no código-fonte. Ao guardar um documento numa coluna de texto em vez de uma coluna JSON nativa.

Em todos esses casos as aspas internas precisam atravessar uma camada de análise que, de outra forma, as trataria como terminadores, e o escape é o que as leva intactas até o outro lado.

As regras de escape, caractere por caractere

O JSON define exatamente quais caracteres não podem aparecer literalmente dentro de uma string. As aspas duplas encerrariam a string antes da hora, então viram \". A barra invertida inicia um escape, então é duplicada para \\. Todo caractere de controle abaixo de U+0020 é proibido, e cinco deles têm formas curtas: quebra de linha é \n, retorno de carro é \r, tabulação é \t, backspace é \b e form feed é \f. Todo o resto nessa faixa vira um escape de seis caracteres, como \u0000.

Dois caracteres costumam ser escapados sem que isso seja obrigatório. A barra normal pode ser escrita como \/, o que é válido e desnecessário; o hábito vem de embutir JSON dentro de HTML, onde a sequência </script> encerraria o elemento script antes da hora. Caracteres fora do ASCII também podem ser escritos como escapes \u, algo que algumas bibliotecas fazem por padrão para manter a saída em ASCII puro.

Esta ferramenta deixa os dois como estão, porque uma saída legível gera diffs melhores e todo parser trata as duas formas de maneira idêntica. Se um sistema mais adiante realmente precisa de saída só em ASCII, isso é uma opção do serializador, não algo que o documento exija.

Fazendo o JSON atravessar o shell com segurança

O shell é onde o escape mais costuma dar errado, porque duas camadas de aspas se aplicam ao mesmo tempo. Aspas simples no bash passam tudo literalmente, e é por isso que curl -d '{"name":"value"}' funciona e a mesma string entre aspas duplas não — o shell expande variáveis e remove caracteres antes que o curl sequer veja o conteúdo.

Quando o próprio payload contém uma aspa simples, a forma com aspas simples também quebra, e a resposta robusta é parar de embuti-lo na linha de comando: escreva o corpo em um arquivo e use curl -d @body.json, ou mande por pipe. Para payloads gerados por código, jq -n é mais seguro do que concatenar strings, porque produz JSON válido por construção.

Variáveis de ambiente que guardam JSON são o caso irmão, sobretudo em configuração de CI e no Docker. O valor geralmente precisa sobreviver às aspas do YAML, à expansão do shell e ao parsing da própria aplicação, o que dá três camadas, e o jeito de manter a sanidade é codificar o JSON em base64, passar isso e decodificar no ponto de uso.

Logs estruturados e a marca da codificação dupla

Os pipelines de log cada vez mais esperam um objeto JSON por linha, o que torna os campos pesquisáveis em vez de exigir expressões regulares sobre texto livre. A armadilha é registrar um objeto que já foi serializado: o campo chega como uma string de JSON em vez de um objeto aninhado, e o sistema de logs o indexa como um bloco opaco.

O sinal visível é exatamente a marca que esta ferramenta existe para desfazer — um valor que se lê como {\"id\":42} em vez de {"id":42}. Cada camada extra praticamente dobra as barras invertidas, então contá-las já diz quantas codificações aconteceram.

A correção é no produtor. Passe o objeto para o logger e deixe que ele serialize uma única vez, em vez de serializar por conta própria e passar uma string. Quando a string vem de outro lugar e não pode ser alterada, a maioria das plataformas de log tem um filtro de parsing de JSON capaz de desembrulhar o campo na ingestão, o que é melhor do que fazer isso em cada consulta.

Embutindo um payload dentro de outro documento

Envelopes de webhook, filas de trabalho e logs de auditoria enfrentam o mesmo problema: um invólucro com campos próprios precisa carregar um corpo arbitrário. Serializar esse corpo como string é a resposta simples, e o custo é que o documento interno se torna opaco — não dá para consultá-lo, validá-lo ou indexá-lo sem fazer um segundo parsing.

A alternativa, manter o corpo como objeto aninhado, preserva a capacidade de consulta, mas exige que o schema do invólucro aceite estrutura arbitrária e mistura os dois espaços de nomes aos olhos de qualquer coisa que percorra o documento. A maioria dos sistemas acaba decidindo caso a caso: aninhado onde o corpo é inspecionado, em string onde ele apenas é repassado.

Existe uma terceira opção que vale lembrar quando o payload é grande ou binário: guarde-o em outro lugar e envie uma referência. Uma URL e um checksum no envelope evitam tanto o escape quanto o limite de tamanho, e é assim que a maioria dos fluxos com arquivos grandes acaba funcionando de qualquer forma.

Lendo texto escapado sem ferramenta nenhuma

Desfazer uma codificação no olho é viável para valores curtos e vale a prática, porque mostra o que aconteceu. Uma única camada exibe \" em volta das chaves e dos valores. Duas camadas exibem \\\" e a string em geral aparece envolta em aspas que também estão escapadas. Além disso, as barras invertidas passam a ser mais numerosas que o conteúdo e contar fica mais rápido do que ler.

Uma verificação útil é o começo da string. Um objeto corretamente aninhado começa com uma chave sem escape; um objeto codificado duas vezes começa com aspas seguidas de uma chave escapada, um formato que se aprende a reconhecer de imediato.

No terminal, printf '%s\n' "$value" resolve uma camada e jq -r '.' resolve mais uma, então aplicá-los em sequência e ver as barras invertidas caírem pela metade a cada vez é o equivalente em linha de comando ao que o botão unstringify faz aqui.