JSON Escape

Turn arbitrary text into something safe to put inside a JSON string. Quotes, backslashes, newlines, tabs and control characters are escaped; everything else is left alone.

This is the operation you need when you are embedding a payload, a log line, a SQL query or an HTML fragment into a JSON field by hand.

What has to be escaped, and what does not

JSON defines exactly nine escape sequences, and requires escaping in exactly three situations.

The double quote

Becomes \". It would otherwise end the string.

The backslash

Becomes \\. It would otherwise start an escape.

Control characters, U+0000 to U+001F

A newline becomes \n, a tab \t, a carriage return \r, a backspace \b, a form feed \f. Anything else in that range takes the \uXXXX form.

The forward slash

May be escaped as \/ but does not have to be. Both forms mean the same character. The escape exists so JSON can be embedded inside an HTML script element, where the sequence </ would end it.

Non-ASCII characters

Do not need escaping at all. JSON is UTF-8 and é, 你 and 🎉 are all legal literally. Escaping them is an option here for systems that mangle non-ASCII in transit.

The single quote

Needs nothing. Inside a double-quoted string it is an ordinary character, and \' is not a valid JSON escape.

Surrogates and emoji

A character outside the Basic Multilingual Plane, which includes every emoji, is stored as two UTF-16 code units. Escaping it produces two \u sequences, as in \ud83c\udf89 for a party popper. That is correct and every parser reconstructs the character.

A lone surrogate, one half of such a pair with no partner, is always escaped here even when nothing else is, because emitting it literally produces text that is not well-formed Unicode and corrupts when re-encoded as UTF-8.

The better answer, most of the time

If you are escaping by hand in order to build JSON, stop and serialise instead. JSON.stringify, json.dumps and their equivalents escape every value correctly by construction, and they cannot forget one.

Hand-built JSON is the root cause behind almost every bad-control-character and unterminated-string error there is.

How to do this in code

Escaping in code.

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

Questions

Do I need to escape single quotes?

No. Inside a double-quoted JSON string an apostrophe is an ordinary character, and \' is not a valid JSON escape at all. It is valid in JavaScript and JSON5, which is where the habit comes from.

Should I escape non-ASCII characters?

Not usually. JSON is UTF-8 and accented characters, CJK and emoji are all legal literally. Escape them only when something in the pipeline mangles non-ASCII, which is a reason to fix the pipeline.

What about a Windows file path?

Every backslash doubles: C:\\Users\\priya. A path ending in a single backslash is worse than wrong, because it escapes the closing quote and swallows the rest of your document.