Fixing JSON Syntax Errors in JSON-LD

What one bad character does

A browser treats a <script type="application/ld+json"> element as inert data. It never runs it and never complains about it, which is why a broken block can sit on a live site for months. The consumers that do read it, such as Googlebot, Bing, social platforms and AI crawlers, pass the text to a JSON parser. JSON parsers are all-or-nothing: they either return a complete object or they return an error and nothing else.

The practical effect is wider than people expect:

• The whole script element is lost, not just the property with the mistake. If your Organization, WebSite, BreadcrumbList and Product all live in one @graph, a stray quote in the product description removes all four.
• Other script elements survive. Each block is parsed separately, so a broken review-app block does not take the theme's block down with it. This is one reason tools sometimes report "some" structured data on a page that should have more.
• Rich result tests describe it vaguely. Google's Rich Results Test and Search Console group these under "Unparsable structured data", often with a short message such as a missing comma or a bad escape, but without showing you the template line that caused it.

Because the failure is silent, syntax problems are usually found by accident, after a drop in rich results or a report from an audit tool. The JSON Checker parses every block on the page and reports the syntax first, because nothing else in a block can be checked until it reads cleanly.

Parser messages and what they really mean

Different parsers word the same fault differently. These are the messages you are most likely to meet, with the usual cause behind each.

Pinpointing the fault in a few minutes

Look at the served HTML, not the Elements panel

The Elements panel in developer tools shows the page after scripts have run and after the browser has tidied the markup. For JSON-LD you need the bytes the server actually sent, which is what a crawler receives first. Use view source (Ctrl+U, or Cmd+Option+U on a Mac), or fetch the page from the command line with curl -s https://www.example.co.uk/page/ > page.html. If a tag manager or JavaScript adds the block later, check the rendered version too, since that is a separate source of errors.

Parse every block in one go from the console

Open the page, open the console, and paste this. It tries each block and prints the error for any that fail, together with the text around the failure point.

document.querySelectorAll('script[type="application/ld+json"]').forEach((el, i) => {
  const text = el.textContent;
  try { JSON.parse(text); console.log('Block ' + i + ': OK'); }
  catch (e) {
    const m = /position (\d+)/.exec(e.message);
    const p = m ? Number(m[1]) : 0;
    console.log('Block ' + i + ': ' + e.message);
    console.log(text.slice(Math.max(0, p - 80), p + 20));
  }
});

This checks the rendered DOM, so it catches blocks that scripts inject, but it will not show HTML entities exactly as the server sent them. If the console reports every block as fine and a crawler still says the markup is unparsable, compare against view source.

Parse a saved block on the command line

Save the block's contents, without the script tags, to a file and run python3 -m json.tool block.json or jq . block.json. Python reports a line and column, which is easier to follow in an editor than a character position. Turn on "show invisible characters" or "render whitespace" in your editor as well: non-breaking spaces, zero-width characters and byte order marks are invisible but matter.

Where broken JSON comes from

Almost nobody types invalid JSON by hand into a finished page. It is produced by one of a handful of processes, and finding which one tells you where the lasting fix belongs.

• Templates that glue strings together. A template that writes "name": "{{ title }}" works until a title contains a double quote, a backslash or a line break. This is the single biggest cause, and it affects every page that uses the template.
• Loops that leave a trailing comma. A loop that prints "x", for every item leaves a comma after the last one. So does a list of optional properties where the final one is skipped because it is empty.
• Empty values printed raw. "price": {{ price }}, becomes "price": , when the price is missing. Numbers and booleans have no quotes around them to hide the gap.
• Rich text editors. Content pasted from a word processor brings curly quotes, non-breaking spaces and soft line breaks. Some page builders also convert straight quotes to curly ones when you save a custom HTML block.
• Copied examples. Documentation often shows JSON with // comments, ... placeholders or single quotes for readability. Pasted as-is, they fail.
• Optimisation plugins and minifiers. Tools that combine, minify or defer inline scripts sometimes treat a JSON-LD block as JavaScript and rewrite it, or add attributes that change its type. If a block validates in your template but not on the live page, switch the optimiser off for that element and test again.
• HTML stored in values. A description containing </script> ends the element early, cutting the JSON in half. A description with <a href="..."> breaks the string at the first quote if it is not escaped.

Encoding values properly, by language

The durable fix is the same everywhere: build the data as a native object or array, then turn the whole thing into JSON with the language's own encoder. Encoders escape quotes, backslashes and control characters, never leave trailing commas and write numbers correctly.

Before and after

This fragment was built by joining strings. The inch marks in the product name close the string early and the loop left a comma after the final property:

{
  "@type": "Product",
  "name": "Shelf bracket 6" black",
  "sku": "SB-6-BLK",
}

The same data passed through an encoder produces a block that parses:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Shelf bracket 6\" black",
  "sku": "SB-6-BLK",
  "description": "Powder-coated steel bracket.\nSupports shelves up to 20 cm deep."
}
</script>

Notice the escaped quote after the 6 and the \n in place of a real line break. You would never type these by hand; the encoder writes them for you.

The fix, step by step

Cases that catch people out

• Valid JSON that says less than you think. JSON allows the same key twice, and most parsers quietly keep the last one. A block with two "image" keys parses without complaint, but the first value is gone. The JSON Checker reports duplicate keys because a parser will not.
• Numbers with leading zeros. "postalCode": 01234 is invalid; a leading zero is not allowed in a JSON number. Postcodes, phone numbers and SKUs should always be strings.
• Old CDATA wrappers. Some older themes wrap inline scripts in //<![CDATA[ and //]]>. That is harmless in JavaScript but breaks JSON, because JSON has no comments.
• A byte order mark. A file saved with a byte order mark can put an invisible character before the first brace. Some parsers reject it. Re-save the file as UTF-8 without a BOM.
• Two objects side by side. {...}{...} is not valid. Wrap them in an array, [{...},{...}], or put both in one @graph.
• Blocks added by a tag manager. A custom HTML tag that injects JSON-LD may be editing text with its own variable syntax. Check the rendered output, not the tag's editor, because the variables are substituted at run time.

Catching it before it ships

A parse check is cheap and catches almost all of these faults before a visitor or crawler sees them. This Python script reads every HTML file in a build folder and fails if any JSON-LD block does not parse:

import json, pathlib, re, sys
bad = 0
pattern = re.compile(r'<script[^>]*application/ld\+json[^>]*>(.*?)</script>', re.S | re.I)
for page in pathlib.Path('public').rglob('*.html'):
    for n, block in enumerate(pattern.findall(page.read_text(encoding='utf-8'))):
        try:
            json.loads(block)
        except json.JSONDecodeError as e:
            bad += 1
            print(f'{page} block {n}: {e}')
sys.exit(1 if bad else 0)

On a CMS without a build step, run the same check against a list of live URLs each week, one per template, and after every theme, plugin or app update. Train editors not to paste formatted text into fields that feed structured data, and prefer plain text fields for product names, headlines and summaries. For what to fix once every block parses, the missing required fields guide is the natural next stop.