Escape and unescape JSON strings

The complete list of JSON escapes

Inside a JSON string, exactly three characters must be escaped: the double quote, the backslash, and any character below U+0020. Everything else may appear literally, although two more have optional escapes.

Every other control character below U+0020 — U+0000 through U+001F, minus the five with named escapes — must be written in the \u form: \u0000 for NUL, \u001b for the escape character that begins an ANSI colour code in a captured terminal log.

Sequences that do not exist in JSON, however familiar they look from other languages:

Characters above the basic plane

JSON strings are sequences of UTF-16 code units, so a character outside the Basic Multilingual Plane — every emoji, many CJK extension characters, historic scripts — needs a surrogate pair when written in escaped form.

"😀"                 // literal, perfectly valid
"\ud83d\ude00"   // the same character, as a surrogate pair
"\u{1F600}"          // NOT valid JSON — that is JavaScript syntax

You will almost never write these by hand. Serialise with your language’s JSON library and it handles the pairing; the escaper above does the same. It matters when you are reading someone else’s output and wondering why a single emoji appears as two escapes, or why a string with a “length” of 2 displays as one character.

One consequence worth knowing: a lone surrogate — "\ud800" with no low partner — is accepted by the JSON grammar and by JSON.parse, even though the resulting string cannot be encoded as valid UTF-8. If such a value reaches a strict consumer, or a database with a UTF-8 column, it will be rejected there instead. Validate at the boundary if you accept untrusted text.

Worked examples

{"path": "C:\Users\new\test.txt"}

{"path": "C:\\Users\\new\\test.txt"}

{"key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADAN...\n-----END PRIVATE KEY-----\n"}

{"payload": "{\"id\":1,\"name\":\"Ada\"}"}

{"quote": "She said "hello" loudly"}

{"quote": "She said \"hello\" loudly"}

Escaping in your own code

The correct answer, in every language, is: do not do it by hand.

// JavaScript — JSON.stringify on a string produces a complete literal
JSON.stringify('C:\\Users\\new')       // "\"C:\\\\Users\\\\new\""
JSON.stringify(text).slice(1, -1)      // the same, without the outer quotes

# Python
import json
json.dumps(text)                       # complete literal, with quotes
json.dumps(text, ensure_ascii=False)   # keep é and 😀 literal instead of \u-escaping

# Shell, using jq — -R reads raw text, -s slurps all lines into one string
printf 'line one\nline two' | jq -Rs .

Python’s ensure_ascii deserves a moment. It defaults to True, which escapes every non-ASCII character as \uXXXX. The output is valid, transport-safe over any 7-bit channel, and considerably larger — a document of Japanese text can grow by a factor of three. Setting it to False writes the characters literally, which is smaller and readable, and is safe as long as everything downstream agrees the encoding is UTF-8.

What you should never do is build a JSON string with string concatenation or a template, replacing quotes with a regular expression as you go. Every escaping bug on this page comes from exactly that. Build a value; serialise it.

JSON escaping is not HTML escaping

They solve different problems and do not substitute for one another. JSON escaping makes text survive a JSON parser. HTML escaping makes text survive an HTML parser. A string that is correctly JSON-escaped can still carry <script> tags, because < means nothing special to JSON.

If you take a value out of a JSON document and put it into a page, you must escape it for HTML at that point — or better, avoid the question entirely by assigning to textContent rather than innerHTML. That is what this page does with everything you paste, which is why a value containing <img src=x onerror=alert(1)> shows up here as those literal characters and nothing happens.

The one place the two do interact: </script> inside a JSON string embedded in an inline <script> block will end the block early, because the HTML tokenizer runs first and does not know it is inside a string. That is exactly what the optional \/ escape exists for. Writing <\/script> keeps the JSON identical and stops the HTML parser closing your tag.

Frequently asked questions

Related pages

• JSON formatterPretty-print, tree view and statistics
• “Unexpected token” explainedIncluding every escaping error
• “Unexpected token < … position 0”Your API returned HTML, not JSON
• “Unexpected end of JSON input”Empty bodies, truncation and double-reads
• “JSON.parse: unexpected character”The Firefox and Safari wording, decoded
• JSON validatorExact line and column for every error
• JSON minifierStrip whitespace and measure the saving

Related tools

• Regex testerTest and debug regular expressions against sample text