JSON-LD

It is JSON that says what it means. The W3C specification describes JSON-LD as a lightweight syntax to serialize linked data in JSON, designed so that existing JSON can be read as linked data with minimal changes and used directly as JSON with no knowledge of RDF^[1]. Its current version, JSON-LD 1.1, became a W3C Recommendation on 16 July 2020^[1].

Three keywords do most of the work on a web page. @context names the vocabulary, usually schema.org, so that a term such as name expands to a full identifier; @type sets what kind of thing a node is; and @id gives the thing an identifier of its own, which the specification says should, when followed, lead to a description of it^[1]. With @id, the Organization on the home page and the publisher of an article can be declared one and the same node.

Google prefers it for practical reasons. It supports JSON-LD, Microdata and RDFa equally where the markup is valid, and recommends JSON-LD because it is not interleaved with the visible text, which makes nested items easier to express, and because it can be read when injected into the page by JavaScript^[2].

Injected markup has a cost. Google processes structured data that is in the DOM when it renders a page, but warns that dynamically generated Product markup can make Shopping crawls less frequent and less reliable, an issue for prices and availability that change often^[3].

The format is only the container. What goes in it follows the rules of structured data: Google’s guidelines say not to mark up content that is not visible to readers of the page^[4].

Identifiers are only useful if they resolve. QueryRev’s study checked the links inside another machine-readable file, llms.txt: of the 684 files with at least one link checked, 84.9% had every checked link answer with a page^[5]. The URLs in a JSON-LD block, for logos, images, profiles and @id values, deserve the same check.

Parse it first. A block that is not valid JSON cannot be read, so a stray comma from a template breaks every item in it. Then test the live URL in the Rich Results Test, which Google recommends over pasted code because the code input has JavaScript limits^[3], and watch Search Console’s rich result reports after each release.

Then read it as a graph: list the nodes by @id and @type, and check that each thing appears once, that every reference points to a node that exists, and that the URLs resolve.

Last, compare each value with the rendered page. Valid syntax and true content are different checks, and only the second tells you the markup describes what readers see.

Sample data: an invented site, to show the method.

A publisher’s article template prints two JSON-LD blocks: one from the theme with an Organization named “Fernhollow Press”, one from a plugin naming the publisher “Fernhollow”. Neither has an @id, so the two cannot be joined, and the article’s publisher is a third, separate copy.

The fix is one Organization node with an @id on the home page’s address, and every article’s publisher pointing to that @id instead of repeating the facts. Both versions pass the Rich Results Test; only the second describes one publisher.