Escape e unescape de JSON: quais caracteres precisam ser escapados e como corrigir strings escapadas duas vezes
JSON escape e unescape explicados: quais caracteres o JSON exige escapar, como colocar JSON dentro de uma string e como corrigir aspas escapadas duas vezes.
Atualizado em 8 de novembro de 202610 min de leitura
Para fazer o escape JSON de um texto, você coloca uma barra invertida antes de cada aspa dupla e de cada barra invertida, troca as quebras de linha e as tabulações por \n, \r e \t e envolve o resultado em aspas duplas. O unescape faz o contrário: \" volta a ser uma aspa e \n volta a ser uma quebra de linha real. Essas são quase todas as regras, e a ferramenta Escape Unescape de String JSON as aplica com exatidão, nos dois sentidos. A maior parte dos problemas vem do que acontece em volta dessas regras: JSON colado dentro de outra string JSON, barras invertidas que se multiplicam toda vez que um valor é salvo e caracteres que são válidos em JSON, mas quebram o lugar onde você os cola. Este guia trata de cada um desses casos.
O que é escapar em JSON e quais caracteres precisam disso
Uma string JSON começa e termina com aspas duplas. Tudo o que estiver dentro e puder ser confundido com o fim da string ou com o início de um escape precisa ser escrito de outro jeito. O padrão JSON (RFC 8259) torna obrigatório o escape de exatamente três grupos de caracteres: a aspa dupla, a barra invertida e todos os caracteres de controle de U+0000 a U+001F, entre eles a quebra de linha e a tabulação. Todo o resto, incluindo letras acentuadas, emojis, apóstrofos e a barra comum, pode aparecer como está.
| Caractere | Escrito em JSON como | Obrigatório? |
|---|---|---|
| Aspa dupla " | \" | Sim, senão ela termina a string |
| Barra invertida \ | \\ | Sim, senão ela inicia um escape |
| Quebra de linha (line feed) | \n | Sim, uma quebra de linha real dentro da string é inválida |
| Retorno de carro | \r | Sim |
| Tabulação | \t | Sim |
| Backspace, avanço de página | \b, \f | Sim |
| Outros controles U+0000 a U+001F | \u0000 a \u001f | Sim, não existe forma curta |
| Barra comum / | / ou \/ | Não, as duas formas são válidas |
| Não-ASCII, como é ou 😀 | como está, ou \u00e9 e o par D83D DE00 | Não, as duas formas são válidas |
| Apóstrofo ' | como está | Não, e \' não é um escape válido |
A última linha pega muita gente. JavaScript e Python aceitam \' dentro de uma string, então parece natural, mas o JSON não define esse escape. Um parser que encontra \' para com um erro. Em JSON o apóstrofo não precisa de escape nenhum, e aspas simples nunca podem ser usadas para delimitar uma string.
Escape ou unescape: qual você precisa
| Sua situação | Direção | O que você recebe |
|---|---|---|
| Uma consulta SQL de várias linhas, um certificado ou um template precisa virar um único valor JSON | Escape | Uma linha só, com \n onde estavam as quebras |
| Uma string cheia de aspas precisa ir para um arquivo de configuração ou um fixture de teste | Escape | Cada " escrita como \" |
| Uma linha de log ou um campo de API aparece como uma fileira única de \n e \" | Unescape | O texto legível, com quebras de linha reais |
| Um campo guarda um documento JSON inteiro como string | Unescape | O documento interno, pronto para o Formatador JSON |
| Você quer conferir se o texto escapado diz o que você acha | Escape e depois Trocar | Uma ida e volta que deve devolver o original exatamente |
Escapar não é criptografar nem compactar. Só muda a forma de escrever os caracteres especiais para que um parser os leia como texto. Se você precisa transformar dados binários, como uma imagem, em texto, isso é outro trabalho, explicado em o que é a codificação Base64. Se o texto vai para um endereço web, ele precisa de codificação percentual com o codificador de URL.
Como escapar ou desescapar uma string JSON, passo a passo
Escolha a direção
Abra a ferramenta de escape JSON e escolha Escape para transformar texto simples em um literal de string JSON, ou Unescape para transformar uma string JSON de volta em texto.
Adicione seu texto
Cole na caixa e clique em Usar este texto, ou solte um arquivo .json, .txt, .log, .ndjson ou outro arquivo de texto parecido na área de envio. UTF-8 e UTF-16 são reconhecidos.
Ajuste as opções
No Escape, Envolver o resultado em aspas já vem ligado; desligue se você for colar o resultado entre aspas que já existem no seu código. As outras três opções são explicadas mais abaixo. No Unescape, deixe Camadas a remover em Automático (até 10), a menos que queira parar no meio do caminho.
Execute e confira as contagens
Clique em Escape ou Unescape. O resultado aparece ao lado da origem com a contagem de caracteres e de bytes e uma taxa de crescimento, que importa quando o valor precisa caber em uma coluna ou em um limite de tamanho de requisição.
Copie, baixe ou troque
Copie o resultado, baixe como arquivo de texto ou clique em Trocar para mandá-lo de volta para a entrada na direção oposta e confirmar que você recupera o texto original.
Transforme texto em uma string JSON ou decodifique uma de volta, com as camadas aninhadas removidas automaticamente. Grátis: um arquivo ou texto colado de até 10 MB, com todas as opções. Pro: sem limite fixo de tamanho e até 20 arquivos de uma vez, baixados em um único ZIP. Tudo roda no seu dispositivo, não nos nossos servidores.
Escapar ou desescapar JSONColocar JSON dentro de uma string JSON
Às vezes um documento JSON inteiro precisa viajar como uma única string: o conteúdo de um webhook guardado em uma coluna do banco de dados, um objeto de configurações que passa por uma fila que só aceita texto ou o campo de mensagem de um evento de log. Para isso, você escapa o documento. O objeto {"name":"Ana"} vira a string "{\"name\":\"Ana\"}". Cada aspa interna ganha uma barra invertida, e o conjunto ganha um par de aspas externas.
Antes de escapar um documento, confira se ele é válido: escapar um objeto sem uma vírgula gera uma string perfeitamente válida que guarda um documento quebrado. Passe-o antes pelo Validador JSON. Se o tamanho importa, tire a indentação com o Minificador JSON antes de escapar: cada quebra de linha de um documento formatado vira um \n de dois caracteres e os espaços de indentação são mantidos, então um documento formatado e escapado fica bem maior que um minificado e escapado.
No sentido contrário, quando uma API devolve um campo cujo valor começa com "{\", você está diante de um documento embutido. Desescape uma vez e você recebe JSON de verdade, que depois pode formatar e ler.
Escape duplo: por que as barras invertidas se multiplicam
Cada vez que um valor é escapado, cada barra invertida que já existe é duplicada e cada aspa ganha mais uma. Uma quebra de linha que é \n depois de uma rodada vira \\n depois de duas e \\\\n depois de três. Desescapada uma vez, ela ainda parece escapada, e é por isso que muita gente acha que a ferramenta não funcionou. Funcionou: ela tirou uma camada de várias.
Deixe Camadas a remover em Automático e a ferramenta continua enquanto o resultado ainda for uma string JSON entre aspas, até dez camadas, e depois informa quantas removeu. Escolha um número de 1 a 10 se quiser parar em uma camada interna, por exemplo para entregar um documento embutido ao formatador em vez de continuar decodificando. Um texto comum que só por acaso contém \n nunca é descascado, porque uma camada só é removida quando o que sobra é de fato interpretado como string JSON.
As causas comuns do escape duplo, para você corrigir na origem:
- Serializar duas vezes. Chamar JSON.stringify em JavaScript ou json.dumps em Python sobre algo que já é uma string JSON embrulha tudo de novo. Serialize o objeto uma vez só, no último passo.
- Bibliotecas de log. Loggers estruturados escapam a mensagem, e alguns pipelines escapam o evento inteiro mais uma vez ao repassá-lo.
- Escapar à mão e depois com código. Colocar \" você mesmo e depois passar o texto por um serializador resulta em \\\".
- Copiar de um depurador ou console. Alguns consoles mostram as strings na forma escapada. Copiar essa exibição e escapar de novo acrescenta uma camada.
- Caminhos do Windows. C:\Users\Ana precisa ser escrito como C:\\Users\\Ana em JSON. Colar sem escape gera \U, que não é um escape válido, e escapar duas vezes gera quatro barras invertidas por separador.
Escapar de acordo com o destino da string
Tudo o que vem a seguir produz JSON válido de qualquer forma. As três opções extras da ferramenta existem porque às vezes o destino se importa.
| Opção | Ligue quando | Custo |
|---|---|---|
| Escapar não-ASCII como \uXXXX | O valor passa por um sistema que não lida bem com UTF-8, ou você quer ASCII puro no controle de versão | é passa de 2 bytes para 6; um emoji, de 4 bytes para 12, como dois escapes |
| Escapar as barras como \/ | A string vai dentro de um bloco script do HTML, onde </script> numa string fecharia a tag antes da hora | Um byte a mais por barra |
| Escapar separadores de linha (U+2028, U+2029) | O literal é colado em código JavaScript para motores antigos, nos quais esses dois caracteres invisíveis eram erro de sintaxe | Seis bytes em vez de três por caractere |
Colar em código é um caso à parte. Um literal de string JSON costuma ser também uma string válida em JavaScript, Python e Go, então você pode colar o resultado escapado entre as suas próprias aspas com a opção de aspas desligada. Em um shell, envolva o corpo JSON em aspas simples e as aspas duplas de dentro não precisam de mais nenhum escape; no prompt de comando do Windows não existem strings entre aspas simples, então cada aspa dupla interna precisa ser escrita como \" para a linha de comando, o que é uma segunda camada, separada, por cima da do JSON.
Quando o unescape falha: o que o erro significa
| Mensagem | Causa comum | Solução |
|---|---|---|
| A string nunca é fechada | O valor foi cortado por um limite de tamanho do log ou por uma cópia incompleta | Cole o valor inteiro ou acrescente a aspa de fechamento |
| Sequência de escape desconhecida | Uma barra invertida antes de uma letra que o JSON não define, como \' ou \U num caminho do Windows | Duplique a barra invertida ou escape o texto original |
| Escape \u incompleto | \u não é seguido de exatamente quatro dígitos hexadecimais | \u12 é inválido; escreva \u0012 |
| Caractere de controle cru | Uma quebra de linha ou tabulação real está dentro da string, muitas vezes depois de copiar de um terminal | Use o Escape nesse texto |
| Conteúdo extra depois da string | Duas strings lado a lado, ou texto depois da aspa de fechamento | Converta um valor de cada vez |
| Isso é um documento JSON, não uma string | Você colou um objeto ou um array | Use o formatador ou o validador; o Unescape trabalha com uma única string |
Cada mensagem informa a linha e a coluna e mostra o texto ao redor, então numa linha de log longa você vê exatamente qual barra invertida é o problema, sem precisar procurá-la.
Perguntas frequentes
Como escapar aspas duplas em JSON?
Coloque uma barra invertida antes de cada uma, de modo que " vire \". Qualquer barra invertida que já esteja no texto precisa ser duplicada antes, senão o resultado será lido de outro jeito. Colar o texto no modo Escape faz as duas coisas e envolve o resultado em aspas.
Como desescapar uma string JSON online?
Escolha Unescape, cole a string com ou sem as aspas e execute. Deixe as camadas em Automático se o valor pode ter sido escapado mais de uma vez; a ferramenta informa quantas camadas removeu.
Por que meu JSON tem uma barra invertida antes de cada aspa?
O valor foi salvo como string em vez de objeto, geralmente porque foi serializado duas vezes. Desescape para recuperar o JSON interno e depois corrija o código que o serializa para que isso aconteça uma vez só.
Posso usar aspas simples ou \' em JSON?
Não. Strings JSON precisam usar aspas duplas, e \' não é um escape válido. Um apóstrofo dentro de uma string entre aspas duplas fica como está e não precisa de barra invertida.
Preciso escapar barras comuns em JSON?
Não. Tanto / quanto \/ são válidas e significam a mesma coisa. Escapar só ajuda quando o JSON vai dentro de uma tag script do HTML, onde o texto </script> fecharia a tag.
Qual o tamanho de texto que posso escapar grátis?
A versão grátis aceita um arquivo ou texto colado de até 10 MB, com todas as opções e todas as profundidades de unescape. O Pro tira o limite fixo, vai até o que o seu dispositivo aguenta e aceita até 20 arquivos de uma vez.