Escapar JSON

Transforme um texto qualquer em algo seguro para colocar dentro de uma string JSON. Aspas, barras invertidas, quebras de linha, tabulações e caracteres de controle são escapados; todo o resto fica como está.

É a operação de que você precisa quando está embutindo à mão um payload, uma linha de log, uma consulta SQL ou um trecho de HTML dentro de um campo JSON.

O que precisa ser escapado e o que não precisa

O JSON define exatamente nove sequências de escape e exige escape em exatamente três situações.

A aspa dupla

Vira \". Do contrário encerraria a string.

A barra invertida

Vira \\. Do contrário iniciaria um escape.

Caracteres de controle, de U+0000 a U+001F

Uma quebra de linha vira \n, uma tabulação \t, um retorno de carro \r, um backspace \b, um form feed \f. Qualquer outro nessa faixa assume a forma \uXXXX.

A barra normal

Pode ser escapada como \/ mas não precisa. As duas formas significam o mesmo caractere. O escape existe para que JSON possa ficar dentro de um elemento script do HTML, onde a sequência </ encerraria o elemento.

Caracteres não ASCII

Não precisam de escape nenhum. JSON é UTF-8 e é, 你 e 🎉 são todos legais literalmente. Escapá-los é uma opção aqui, para sistemas que estragam não ASCII no caminho.

A aspa simples

Não precisa de nada. Dentro de uma string com aspas duplas é um caractere comum, e \' não é um escape JSON válido.

Substitutos e emojis

Um caractere fora do Plano Multilíngue Básico, o que inclui todo emoji, é guardado como duas unidades de código UTF-16. Escapá-lo produz duas sequências \u, como \ud83c\udf89 para uma língua de sogra. Isso está correto e qualquer parser remonta o caractere.

Um substituto solitário, metade de um par desses sem o par, é sempre escapado aqui mesmo quando nada mais é, porque emiti-lo literalmente produz texto que não é Unicode bem formado e se corrompe ao ser recodificado para UTF-8.

A resposta melhor, na maior parte das vezes

Se você está escapando à mão para montar JSON, pare e serialize em vez disso. JSON.stringify, json.dumps e equivalentes escapam cada valor corretamente por construção, e não têm como esquecer um.

JSON montado à mão é a causa raiz de quase todo erro de caractere de controle inválido e de string não terminada que existe.

How to do this in code

Escapando em código.

// Escaped and quoted
const quoted = JSON.stringify(text);

// Escaped without the surrounding quotes
const escaped = JSON.stringify(text).slice(1, -1);

import json

quoted = json.dumps(text)                      # with quotes, non-ASCII escaped
quoted = json.dumps(text, ensure_ascii=False)  # with quotes, é stays é
escaped = json.dumps(text)[1:-1]

# jq's @json filter escapes and quotes
printf '%s' "$text" | jq -Rs @json

# -R reads raw input, -s slurps it into one string

b, _ := json.Marshal(text)   // includes the quotes

// Marshal escapes <, > and & by default for HTML safety.
// To turn that off you need an Encoder:
var buf bytes.Buffer
enc := json.NewEncoder(&buf)
enc.SetEscapeHTML(false)
enc.Encode(text)

Perguntas frequentes

Preciso escapar aspas simples?

Não. Dentro de uma string JSON com aspas duplas, um apóstrofo é um caractere comum, e \' não é sequer um escape JSON válido. Ele é válido em JavaScript e em JSON5, que é de onde vem o hábito.

Devo escapar caracteres não ASCII?

Em geral não. JSON é UTF-8 e caracteres acentuados, CJK e emojis são todos legais literalmente. Escape-os só quando algo no pipeline estraga não ASCII, o que é um motivo para consertar o pipeline.

E um caminho do Windows?

Cada barra invertida dobra: C:\\Users\\priya. Um caminho terminado em uma única barra invertida é pior que errado, porque escapa a aspa de fechamento e engole o resto do seu documento.