How are string escape errors in structured data diagnosed?

Definition: A string escape error is a JSON syntax failure inside a quoted value, often caused by a backslash that does not introduce a permitted escape or by an incomplete Unicode escape. In JSON-LD, the JSON layer must parse before the structured data can be interpreted.

Key facts

• Google's Unparsable structured data report lists structured data that could not be parsed because of a serious syntax error, so its intended type cannot be determined.
• The same Google help page labels an unescaped quotation mark example as an empty escape sequence and an unknown \q sequence as a bad escape sequence.
• Google's documented Unicode messages distinguish a missing part of a surrogate pair from a missing \u marker, a non-four-digit escape, and a non-hexadecimal digit.
• RFC 8259 requires quotation marks, reverse solidus characters, and control characters from U+0000 through U+001F to be escaped inside JSON strings.
• The W3C JSON-LD 1.1 Recommendation states that JSON-LD is compatible with JSON, so a JSON parser can be reused for the serialization layer.

What does Google's report tell you?

Google's Unparsable structured data report is available when Google finds structured data that cannot be parsed. It describes the entries as critical structured data errors, and it sorts errors by severity based on affected pages and other factors. If one error affects several pages, Google identifies an underlying template error as the most common cause.

The report names syntax failures separately from value-type failures. Invalid JSON document means that the JSON has a top-level syntax error. Incorrect value type means that a field received a value of the wrong type, such as a string where a number or array was expected.

How are quotation marks and backslashes checked?

JSON strings begin and end with quotation marks. RFC 8259 says that quotation marks and the reverse solidus, the backslash character, must be escaped when they occur inside a string. Its grammar allows \", \\, \/, \b, \f, \n, \r, \t, and \u followed by four hexadecimal digits.

For a string containing quotation marks, the backslash belongs immediately before each embedded quotation mark. Google's report gives this pair of examples:

{
  "description": "Call me \"John\""
}

An isolated backslash before an ordinary character produces Google's Empty escape sequence in string message. A sequence such as \q produces Bad escape sequence in string, because q is not one of the JSON escape forms. Inspect the page source or rendered JSON-LD and count the backslashes that reach the HTML document.

How are Unicode parsing errors separated?

RFC 8259 permits a Basic Multilingual Plane character to use \u plus four hexadecimal digits. It represents a character outside that plane with a UTF-16 surrogate pair, such as \uD834\uDD1E for the G clef character. The specification also says that networked JSON text must use UTF-8.

Google's error table maps the failure location to a message. Truncated Unicode character means that the last six characters of a Unicode surrogate pair are missing. Invalid Unicode character means that the second half lacks its \u token. Invalid Unicode escape sequence: four digits expected means that the escape has the wrong length, while Invalid Unicode escape sequence: hexadecimal digit expected means a hexadecimal digit is missing.

Use a small isolated value when debugging a generated block:

{
  "name": "G clef \uD834\uDD1E",
  "description": "Call me \"John\""
}

The W3C JSON-LD 1.1 specification describes a JSON-LD document as JSON and defines its internal representation with strings, numbers, booleans, null, arrays, and maps.

How is a correction validated?

After correcting the source, validate the complete JSON-LD block rather than only the field named in the error. RFC 8259 says that a JSON parser must accept texts conforming to the JSON grammar, while a JSON generator must produce text that strictly conforms to it. Run the corrected block through a JSON parser, then run Google's structured data test or the relevant Search Console validation flow. Google's help page instructs site owners to select Validate Fix after fixing an issue and warns that additional warnings or errors can appear once the item becomes parseable.

Related terms

• JSON-LD
• Structured data
• UTF-8 encoding

FAQ

Why does an escaped quotation mark break structured data?

The quotation mark closes a JSON string unless a reverse solidus immediately escapes it. You can write \" inside the string, as in Google's example, while a bare quotation mark changes the JSON structure.

What does a bad escape sequence mean?

It means the character after a backslash is not a permitted JSON escape. Google's example uses \q; replace the sequence with the intended character or encode that character using a valid JSON form.

Does a valid JSON block prove that the structured data is valid?

No. It establishes that the JSON layer can be parsed. Google separately reports incorrect value types and other structured data issues after the item can be read.

Sources

1. Google Search Console Help, "Unparsable structured data report", undated
2. IETF, "The JavaScript Object Notation (JSON) Data Interchange Format", December 2017
3. W3C, "JSON-LD 1.1: A JSON-based Serialization for Linked Data", 16 July 2020

---

Check how a page reads to answer engines. Open the GEO score analyzer