Add note about `\u` entities being decoded via `JSON.parse()`.

Open Beginner friendly
#499 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
html, json
Domain
documentation

Research direction

Start with the specification source for Example 147, linked in the issue, and review the surrounding JSON-LD-in-HTML guidance and issue #498. Add a short note and possible example showing that JSON.parse() converts the \u0026 escape before further JSON-LD processing. The work is done when the example clearly distinguishes JSON parsing from later HTML or JSON-LD handling.

Written by the indexing model from the issue text.

Description

This came up in #498 which pointed to confusion and incorrect expectations set by https://validator.schema.org/ and various search engines whose processing previously went "beyond" text extraction + JSON.parse() (+/- full JSON-LD processing) and included HTML entity extraction within values in which they expected HTML (such as schema:description etc.). Google has apparently now changed that (as of 2026-08-26). However, that's increased the confusion around what SHOULD be handled, by whom, when.

I propose we add a short note and possible an example just below this one:
https://www.w3.org/TR/json-ld11/#example-147-embedding-json-ld-containing-html-in-html

In the new example we would change that text to use \u0026lt; instead of < and note that JSON.parse() will make the \u0026 into an & prior to any further JSON-LD processing.

This goes above and beyond (imo) to explain parsing "gotchas" implicit in the using HTML data blocks for any JSON. However, because issue #498 was raised and JSON-LD's strong association with SEO, I think we should make it clear how the technology works even if the previous approaches around indexing did more behind the scenes than was required by HTML, JSON, or JSON-LD.

Dominant language
HTML
Stars
139
Forks
23
No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from w3c/json-ld-syntax

All issues in w3c/json-ld-syntax

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.