Escape / unescape de strings JSON

O que esta ferramenta faz

Uma string JSON não pode conter aspas duplas em bruto, uma barra invertida em bruto nem uma quebra de linha literal: o formato precisa desses caracteres para marcar onde as strings começam e acabam. Por isso são escritos como sequências de escape, e esta ferramenta converte entre as duas formas. Cole texto normal e obtenha a versão com escape, pronta a inserir em JSON; troque de sentido e o texto com escape volta a ser legível.

É o segundo sentido que costuma trazer as pessoas aqui: uma linha de registro, uma mensagem de erro ou uma resposta de curl que chegou como um muro de barras invertidas. Tudo roda no seu navegador, o que importa quando aquilo que está tentando ler é uma resposta de produção.

As sequências de escape

O JSON define uma lista curta de escapes, e a ferramenta usa exatamente essa lista — nada mais exótico, porque tudo o resto não é JSON válido.

• \" — aspas duplas, que de outra forma terminariam a string.
• \\ — uma única barra invertida. É por isso que os caminhos do Windows e os padrões de expressões regulares duplicam.
• \n e \r — quebra de linha e retorno de carro.
• \t — tabulação. Também existem \b e \f, para retrocesso e avanço de página.
• \/ — um escape opcional para a barra. Válido, nunca obrigatório; esta ferramenta aceita-o e nunca o produz.
• \uXXXX — qualquer caractere pelo seu código hexadecimal, que é como se escrevem os caracteres de controle e tudo o que esteja fora do ASCII.

Os caracteres de controle — tudo abaixo do código 32 — não têm qualquer forma literal dentro de uma string JSON, por isso saem sempre como escapes \uXXXX, mesmo que não tenha pedido saída ASCII.

Por que as barras invertidas se multiplicam

A razão mais comum para recorrer a uma ferramenta destas é texto que sofreu escape mais do que uma vez. Cada ronda de codificação faz escape às barras invertidas introduzidas pela anterior, por isso um único caractere de aspas fica com uma cauda cada vez mais longa:

original    He said "hi"
escaped     He said \"hi\"
escaped x2  He said \\\"hi\\\"

Isto acontece quando um valor é serializado para JSON, esse JSON é armazenado como string dentro de outro documento JSON, e o resultado vai para os registros. Decodificar uma vez desfaz uma camada; volte a rodar sobre o resultado até o texto se ler normalmente. Se decodificar e a saída ainda tiver barras soltas, é mesmo uma camada extra, não uma falha da conversão.

Aspas: valor ou fragmento

Um valor string JSON completo inclui as aspas duplas envolventes. Mas na maior parte das vezes está colando dentro de uma string que já existe no seu código ou configuração, onde essas aspas estariam a mais. Por isso o escape produz por padrão apenas o conteúdo com escape, e a opção «incluir aspas envolventes» acrescenta-as quando quer um valor para colar inteiro.

A decodificação não precisa dessa escolha — aceita as duas formas. Cole um fragmento ou cole um valor entre aspas completo tirado diretamente de um documento JSON, e as aspas envolventes são reconhecidas e removidas.

Unicode, e quando lhe fazer escape mesmo assim

O JSON é um formato Unicode. «שלום» e «😀» são strings JSON perfeitamente válidas tal como estão escritas, e deixá-las legíveis é o comportamento padrão aqui. A opção \uXXXX existe para os sistemas que ficaram para trás: pipelines de registros antigos, terminais e analisadores que assumem ASCII e estragam tudo o resto.

Há um detalhe que conta quando essa opção está ligada. Os caracteres fora do intervalo básico — a maioria dos emoji — são armazenados internamente como duas unidades a que se chama par substituto, e o formato exige que ambas as metades sejam escritas como escapes separados. Um emoji passa então a dois escapes \u e não a um mais longo. As ferramentas que erram nisto produzem escapes que nenhum analisador aceita, o que costuma explicar os emoji que sobrevivem a um sistema e se partem no seguinte.

Quando a decodificação falha

Nem toda a sequência com barra invertida é um escape válido. \q não significa nada em JSON, e \u12 é um escape \u a que falta metade dos dígitos. Em vez de os deixar passar inalterados e devolver uma saída que parece certa mas não é o que os seus dados diziam, a ferramenta para e indica a linha e a coluna exatas onde a sequência defeituosa começa.

Na prática esse erro é informativo: um \q solto costuma significar que o texto nunca sofreu escape para JSON, e um \u truncado costuma significar que a entrada foi cortada — uma linha de registro aparada por um limite de comprimento, ou uma cópia que parou a meio da sequência.