Escape JSON

Trasforma un testo qualsiasi in qualcosa che si possa mettere in sicurezza dentro una stringa JSON. Virgolette, backslash, a capo, tabulazioni e caratteri di controllo ricevono l’escape; tutto il resto resta com’è.

È l’operazione che serve quando incorpori a mano un payload, una riga di log, una query SQL o un frammento di HTML dentro un campo JSON.

Che cosa va escapato e che cosa no

JSON definisce esattamente nove sequenze di escape e ne richiede l’uso in esattamente tre situazioni.

La virgoletta doppia

Diventa \". Altrimenti chiuderebbe la stringa.

Il backslash

Diventa \\. Altrimenti aprirebbe un escape.

I caratteri di controllo, da U+0000 a U+001F

Un a capo diventa \n, una tabulazione \t, un ritorno a capo \r, un backspace \b, un salto pagina \f. Tutto il resto in quell’intervallo prende la forma \uXXXX.

La barra

Può essere escapata come \/ ma non è obbligatorio. Le due forme indicano lo stesso carattere. L’escape esiste perché il JSON possa stare dentro un elemento script HTML, dove la sequenza </ lo chiuderebbe.

I caratteri non ASCII

Non richiedono alcun escape. JSON è UTF-8 e é, 你 e 🎉 sono tutti leciti alla lettera. Qui escaparli è un’opzione, per i sistemi che rovinano il non ASCII lungo il percorso.

L’apice singolo

Non richiede nulla. Dentro una stringa tra virgolette doppie è un carattere qualunque, e \' non è un escape JSON valido.

Surrogati ed emoji

Un carattere fuori dal Basic Multilingual Plane, categoria che comprende ogni emoji, è memorizzato come due unità di codice UTF-16. Escaparlo produce due sequenze \u, come \ud83c\udf89 per una lingua di Menelicche. È corretto e ogni parser ricostruisce il carattere.

Un surrogato spaiato, metà di una coppia del genere senza il suo partner, qui viene sempre escapato anche quando nient’altro lo è, perché emetterlo alla lettera produce testo che non è Unicode ben formato e che si corrompe alla ricodifica in UTF-8.

La risposta migliore, quasi sempre

Se stai escapando a mano per costruire del JSON, fermati e serializza invece. JSON.stringify, json.dumps e i loro equivalenti escapano correttamente ogni valore per costruzione, e non possono dimenticarne uno.

Il JSON costruito a mano è la causa profonda di quasi tutti gli errori di carattere di controllo non valido e di stringa non terminata che esistono.

How to do this in code

Fare l’escape nel codice.

// 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)

Domande frequenti

Devo escapare gli apici singoli?

No. Dentro una stringa JSON tra virgolette doppie un apostrofo è un carattere qualunque, e \' non è affatto un escape JSON valido. Lo è in JavaScript e in JSON5, da cui viene l’abitudine.

Conviene escapare i caratteri non ASCII?

Di solito no. JSON è UTF-8 e caratteri accentati, CJK ed emoji sono tutti leciti alla lettera. Escapali solo quando qualcosa nella catena rovina il non ASCII, il che è un buon motivo per sistemare la catena.

E un percorso di Windows?

Ogni backslash raddoppia: C:\\Users\\priya. Un percorso che finisce con un solo backslash è peggio che sbagliato, perché escapa la virgoletta di chiusura e si mangia il resto del documento.