One of my page headings, Your <em>IP</em>, plainly, showed up in the JSON-LD as "Your IP , plainly". The same bug was in the structured data of 62 pages. On screen, every one of them looked right.
The site is MyIPScan, which I built. This post is about the bug class, how it happens, and a test that catches it.
TL;DR
- If you derive a JSON-LD headline from heading HTML, inline tags like
<em>can leave a space before punctuation:Your <em>IP</em>, plainly→Your IP , plainly. - Fix: delete inline tags without replacing them, and turn only block boundaries into spaces.
- Catch it at build time: the JSON-LD
headlinemust equal the visible heading's normalized text, and no generated text field may match/ [,.;:!?)]/.
Why one space matters
JSON-LD is a copy of your page written for machines, and no human reads it. Google recommends JSON-LD for structured data when your setup allows it (Search Central intro), and its guidelines say: "Your structured data must be a true representation of the page content" (General Structured Data Guidelines).
The headline was still true, just sloppy. But a template stamps the same mistake onto every page it builds, and nothing on screen tells you. The visible heading was correct on all 62 pages.
Checking the page in a browser is real QA. For this bug it checked the wrong output.
Two explanations that don't fit
The source text. If the space were in the CMS, the visible heading would show it too. It didn't. A bug in the source shows up in both copies.
JSON escaping. JSON.stringify escapes quotes, backslashes and control characters. It does not add spaces.
That leaves the step that turns heading HTML into a string. I can't show you my original generator, but the output has the fingerprint of one specific mistake.
How this class of bug happens
The code below is an illustration of the bug class, not my generator. It reproduces the exact output, which is enough to reason about it.
A common way to strip HTML tags in JavaScript replaces every tag with a space, so that <p>one</p><p>two</p> doesn't become onetwo. Then it squeezes whitespace:
// Illustration: a naive stripper that turns every tag into a space
function naiveStrip(html) {
return html.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim();
}
naiveStrip('Your <em>IP</em>, plainly');
// "Your IP , plainly"
naiveStrip('What is my <em>IP address</em>?');
// "What is my IP address ?"
Step by step:
Your <em>IP</em>, plainly- Tags → spaces:
Your IP , plainly(two spaces after "Your", one before the comma) - Collapse whitespace:
Your IP , plainly
The collapse hides half the damage. The double space after "Your" merges into one, so the result looks almost right. The space before the comma has nothing to merge with, so it stays.
The rule the stripper breaks: inline elements do not create word boundaries; block elements do. <em> sits inside a run of text. <p>, <li>, <h2> and <br> end one.
textContent and innerText
In a DOM, textContent "returns the concatenation of the textContent of every child node" (MDN), so <em> is harmless. It also includes <script> and <style> content, and it ignores <br>: in Chromium, Line one<br>line two gives "Line oneline two". innerText handles <br>, but for an element that isn't rendered, such as one in a detached tree, it returns the same as textContent (MDN). In a static build step with no browser, that is the case you are in.
The fix, as an illustration
For a heading, which is short and mostly inline, a small explicit function is enough. It deletes 26 inline tags and turns everything else into a space:
const INLINE = /<\/?(a|abbr|b|bdi|bdo|cite|code|data|dfn|em|i|kbd|mark|q|s|samp|small|span|strong|sub|sup|time|u|var|wbr)\b[^>]*>/gi;
function headingText(html) {
return html
.replace(INLINE, '') // inline tags: no boundary
.replace(/<br\s*\/?>/gi, ' ') // line break: boundary
.replace(/<[^>]*>/g, ' ') // any other tag: boundary
.replace(/ /g, ' ')
.replace(/\s+/g, ' ')
.trim();
}
headingText('Your <em>IP</em>, plainly'); // "Your IP, plainly"
headingText('What is my <em>IP address</em>?'); // "What is my IP address?"
headingText('Line one<br>line two'); // "Line one line two"
The comments are real output from Node 22. This version decodes only . If your headings contain & or ’, decode them properly (the test below shows a minimal decoder). If your build already has an HTML parser, use it instead of regex. The point is the boundary rule.
One design choice helps more than the function: build the visible heading and the JSON-LD headline from the same string, not from two code paths. Then they can't drift.
A Node test for the JSON-LD headline
The function fixes one build. A test keeps the next refactor from bringing the bug back. This one reads the built HTML, so it checks what a crawler fetches, not the template:
// jsonld.test.mjs (run: node --test jsonld.test.mjs)
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync, readdirSync } from 'node:fs';
import { join } from 'node:path';
const INLINE = /<\/?(a|abbr|b|bdi|bdo|cite|code|data|dfn|em|i|kbd|mark|q|s|samp|small|span|strong|sub|sup|time|u|var|wbr)\b[^>]*>/gi;
const ENT = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
const decode = (s) => s.replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (m, e) =>
e[0] !== '#' ? (ENT[e.toLowerCase()] ?? m)
: String.fromCodePoint(e[1].toLowerCase() === 'x' ? parseInt(e.slice(2), 16) : +e.slice(1)));
const text = (html) => decode(html.replace(INLINE, '').replace(/<[^>]*>/g, ' '))
.replace(/\s+/g, ' ').trim();
function* pages(dir) {
for (const e of readdirSync(dir, { withFileTypes: true })) {
const p = join(dir, e.name);
if (e.isDirectory()) yield* pages(p);
else if (e.name.endsWith('.html')) yield p;
}
}
// every JSON-LD block, any attribute order
const blocks = (html) => [...html.matchAll(
/<script\b[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi
)].map((m) => JSON.parse(m[1]));
// walk objects, arrays and @graph; yield [key, string] for the fields we check
const FIELDS = new Set(['headline', 'name', 'description']);
function* fields(node) {
if (Array.isArray(node)) for (const n of node) yield* fields(n);
else if (node && typeof node === 'object') {
for (const [k, v] of Object.entries(node)) {
if (FIELDS.has(k) && typeof v === 'string') yield [k, v];
else yield* fields(v);
}
}
}
const SPACE_BEFORE_PUNCT = / [,.;:!?)]/;
for (const file of pages(process.env.DIST ?? 'dist')) {
test(file, () => {
const html = readFileSync(file, 'utf8');
const found = [...fields(blocks(html))];
for (const [key, value] of found) {
assert.doesNotMatch(value, SPACE_BEFORE_PUNCT, `${key}: ${JSON.stringify(value)}`);
}
const h1 = html.match(/<h1\b[^>]*>([\s\S]*?)<\/h1>/i);
const headline = found.find(([k]) => k === 'headline');
if (h1 && headline) assert.equal(headline[1], text(h1[1]));
});
}
I ran it against four small fixture pages: a correct article, the broken headline, a page with &, ' and an @graph, and a FAQPage with no heading and a bad question name. Excerpt of the spec reporter output (node --test --test-reporter=spec, Node 22):
✖ dist/bad/index.html (2.665891ms)
✔ dist/entity/index.html (1.36117ms)
✖ dist/faq/index.html (1.048332ms)
✔ dist/good/index.html (0.35228ms)
...
AssertionError [ERR_ASSERTION]: headline: "Your IP , plainly"
...
AssertionError [ERR_ASSERTION]: name: "Can someone see my <em>IP</em> ?"
The two assertions catch different things:
-
Equality catches any drift between the visible heading and the
headline, whatever the cause. The entity fixture passes becausetext()decodes&and'before comparing. -
The punctuation regex runs on every
headline,nameanddescriptionin every block, including@graphand nested FAQ questions. That covers pages with no heading to compare against.
The regex has false positives. I checked these in Node and all three match: Learn .NET in a weekend, Wait ... what, and French spacing like Bonjour !. Add exceptions if your copy has them.
Checking it by hand
Two free tools show you the parsed JSON-LD for a URL or a pasted snippet:
- Google's Rich Results Test
- The Schema Markup Validator
A stray space is valid Text, so there is nothing for them to flag. They show you the string, and you have to read it. That's why the automated test matters more than the manual check.
The rule
I built MyIPScan, a network privacy toolkit, and this bug sat in its structured data on 62 pages while every page looked fine.
Test the copy you don't look at. Visual QA only checks the page humans see.
Top comments (3)
Funny how the whitespace collapse hides half the damage: the double space disappears and only the one before the comma survives, so at a glance it looks fine. Building the heading and the
headlinefrom one string is the fix I'd push hardest, since it removes the drift instead of testing for it. How did you spot it in the first place, Rich Results Test or just reading the JSON-LD by chance?The equality check against the visible h1 is the strongest part, but on many sites the JSON-LD headline is meant to match the title tag instead, and the two intentionally differ (shorter h1, longer title). Worth allowing either source in the test so it does not train people to ignore failures. The other gap: if any client-side code rewrites headings after hydration, the built HTML passes while the rendered DOM drifts. Do you run the same assertion against the rendered page as well?
The inline-vs-block boundary rule is the whole article. Most strippers get it wrong because
one
two
→ onetwo is the bug everyone remembers, so they over-correct in the other direction and turn everything into a space.Your build-from-the-same-string suggestion is stronger than the headingText() function, though — if the visible heading and the JSON-LD headline come from one source, the stripper becomes irrelevant for that pair. Did you end up doing that, or did the 62 pages get fixed by patching the generator?
The false positives you flagged (Learn .NET, Wait ..., Bonjour !) are worth keeping in the regex as exceptions rather than removing the check — the space-before-punctuation rule catches real bugs far more often than it cries wolf.
The "visual QA only checks the page humans see" line is going in my notes.