CrawlCheck

Guides · 2026-09-30 · By · 2 views

JSON-LD @id errors: what breaks and how to fix it

Six identifier defects no vocabulary validator reports: blank nodes, path @ids that 404, Unicode normalisation, raw IDN hosts, encoding drift and rival roots. Plus the duplicate that is not a defect.

A JSON-LD @id is the IRI that identifies a node in the graph a consumer builds; two nodes with the same @id are one node. Six defects slip past vocabulary validators: blank-node identifiers (_:), path-form @ids that can 404, values not in Unicode NFC, raw internationalised hostnames, percent-encoding that varies on one path, and rival roots (one business under two @ids). The fix is one fragment-form @id per entity on the canonical host, NFC-normalised, referenced rather than restated everywhere.

Check your own site free

About a minute. First scan free with your email, nothing installed.

An @id is not a label. It is an IRI, an internationalised URI, and the graph a consumer builds from your page treats two nodes with the same @id as one node and two nodes with different @ids as two things, whatever their names say. Most pages that carry one got it from a plugin default rather than a decision. Six identifier defects follow from that rule, and no validator checking schema.org vocabulary mentions them, because the vocabulary is fine; it is the identifiers that are wrong.

What an @id is for #

A consumer that reads JSON-LD, whether a search engine, an answer engine or a knowledge-graph pipeline, converts it to triples: subject, predicate, object. The subject of every triple is the node's @id. A node without one gets a blank node, an identifier that exists only inside that one document and can never be referred to from anywhere else. A node with @id https://example.com/#organization can be referenced from every other page on the site, from a Wikidata entry and from another site's sameAs, and all of those references resolve to the same subject. That is the entire value of the field: it lets the world agree on which thing you are.

Six identifier defects to check #

Blank-node identifiers. An @id beginning _: is a blank node written out by hand. It is legal JSON-LD and it is useless as an identity, because _:b0 in your document and _:b0 in anyone else's are unrelated. The fix is to give the node a real IRI on your own domain.

Fragment versus path. An @id on your own host can be in fragment form, https://example.com/#org, or path form, https://example.com/org. Both are valid IRIs. The difference is what happens when someone fetches them. A path IRI is a URL that should return something, and if /org returns a 404, the identifier points at nothing. A fragment IRI resolves to the page that carries the node, which always exists. Fragment form is the safer default for entities that do not have a page of their own.

Unicode normalisation. An IRI containing accented characters can be written in composed form (one code point per accented letter) or decomposed form (base letter plus combining mark). They render identically and compare unequal. The fix is to normalise to NFC before writing the value, which every language runtime can do in one call.

Raw internationalised hostnames. When an @id or url carries a hostname with non-ASCII characters, consumers differ on whether they convert it to punycode before comparing, so the same business can appear under two hosts. Write the punycode form, xn--, in identifiers.

Percent-encoding drift. The same path written with two different encodings, /caf%C3%A9 and /café, decodes to one path and compares as two identifiers.

Rival roots. Two top-level organisation-like nodes with the same normalised name but different @ids are the same business declared as two entities. This is the one that does the most damage, because a consumer has no way to merge them, and the corroboration that one node earns from a directory or a review site does not accrue to the other. Unlinked organisation nodes of this kind turn up on 2.6% of scanned sites. The opposite case, one node parsed twice under the same @id, is not a defect at all; see below.

DefectLooks likeConsequenceFix
blank node"@id": "_:b0"cannot be referenced from anywhereown-domain IRI
path @id that 404shttps://x.com/orgidentifier points at nothingfragment form or a real page
not NFCé as e + combining acutesame string compares unequalnormalise to NFC
raw IDN hosthttps://müller.de/#orgtwo hosts to some consumerspunycode host
encoding drift/caf%C3%A9 and /caféone path, two identifiersone spelling site-wide
rival rootstwo Organization nodes, one name, two @idscorroboration split across two entitiesone @id, referenced everywhere

Two nodes, one @id: duplicate or collision? #

Before calling anything a collision, count the distinct @ids on the live page. Two records sharing an @id are one record appearing twice: a template-level block and a page-level block, or the same block read twice. Compare them and they always look like a perfect collision, same phone, same address, same everything, because every field is the same field. A real collision is two records with different @ids, or none, that claim the same phone number, coordinates or identity.

Read from the live HTMLValue
Business nodes1
Their @idshttps://example.com/#business
Distinct @ids1

We learned this by getting it wrong. CrawlCheck once reported four collisions on one site, including a shared phone and a shared @id, and we wrote it up as a real defect. The live page held one business node; our extraction had read it twice and compared it with itself. The fix was not to ignore shared @ids, which would also hide two different businesses handed one identifier by a careless template. One record read twice now counts once, and a site with two genuinely distinct business nodes still reports two. The lesson for anyone auditing markup: verifying that a check fired is not verifying the finding. For any finding that accuses a site, fetch the page and count the nodes by hand.

The sameAs side #

The same applies to sameAs values, with one extra point for Wikidata. A Wikidata link can be written as https://www.wikidata.org/wiki/Q42, the human page, or http://www.wikidata.org/entity/Q42, the entity IRI. Both are commonly written; only the entity form is the identifier of the thing in Wikidata's own graph. The broader question of whether a sameAs target links back is explained in the entity SEO guide.

How to fix it in one pass #

Choose one @id per entity, in fragment form on your canonical host: https://example.com/#organization for the business, https://example.com/#website for the site, https://example.com/page/#webpage for pages. Write it identically on every page, NFC-normalised, punycode host, one encoding. Reference it, rather than restating the node, wherever another node needs to point at the business: a publisher field that contains {"@id": "https://example.com/#organization"} and nothing else is a reference, and the graph merges it with the full node. Which of two rival roots is the real one is a business fact, not a markup fact: decide it, keep that @id, and point everything else at it.

Checking a page by hand #

View the page source, not the rendered DOM, and copy every <script type="application/ld+json"> block into a JSON parser. List every @id with its host, its form (fragment or path) and its @type. Any identifier beginning _: goes on the fix list at once. For each path-form identifier on your own host, fetch it and note the status; a 404 is a dangling identifier. Sort the remaining list by normalised name and look for the same name under two identifiers, which is the rival-roots case. Then run one more pass over the raw bytes for % sequences and for any non-ASCII character in a hostname. The whole pass takes a few minutes on a typical page and finds the defects the vocabulary validators skip, because those tools check that telephone is a string and never ask what @id points at.

What this is not #

None of this is a schema.org vocabulary check. A page can pass every vocabulary validator and still have two rival roots and a blank node, and a page can carry a warning about a recommended property and be perfectly identified. For which tool checks what, see the schema validators comparison; for where identifier findings appear in a scan, see the report guide. Live shares for each finding are on the dataset page.

Share of scanned sites with each finding in this articleTwo business records share a phone, @id or location2.6%Share of scanned sites with eachfinding in this articleTwo business records share a phone, @id or location2.6%
Read live from the same counters the dataset page uses, at the moment this page was served. Bars are scaled to the largest value shown, not to 100%.

Share this finding:LinkedInXEmailFollow Emmanuel on LinkedIn

Questions this post answers

What is an @id in JSON-LD?

The IRI that identifies the node as a subject in the graph a consumer builds from the page. Two nodes with the same @id are one node; two nodes with different @ids are two things, whatever their names say.

Are two JSON-LD nodes with the same @id a collision?

No. Two nodes with one @id are one subject described twice, and their properties merge. A collision is two records with different @ids, or none, that claim the same phone number, coordinates or identity. Count the distinct @ids on the live page before reporting one.

Is a blank node identifier like _:b0 an error?

It is valid JSON-LD but useless as an identity: it exists only inside that document and cannot be referenced from any other page or from another site's sameAs. Replace it with an IRI on your own domain.

Should @id use a fragment or a path?

Fragment form, such as https://example.com/#organization, resolves to the page carrying the node and always exists. A path form is a URL that should return something, and one that returns 404 points at nothing.

What are rival roots?

Two top-level organisation-like nodes on one page with the same name and different @ids: the same business declared as two entities. Corroboration earned by one does not accrue to the other, and a consumer cannot merge them.

Which Wikidata URL form belongs in sameAs?

The entity form, http://www.wikidata.org/entity/ followed by the item ID, is the identifier of the thing in Wikidata's graph. The /wiki/ form is the human page.

Related findings

The main product

Found this on your own site? We fix it for $100.

Scan free to see where you stand. The fix is one site, every finding implemented and re-measured, with a sealed before and after.

Free browser extension

Check this on any site you open, without leaving the page.

CrawlCheck for Chrome grades every site you visit A–F and shows, from your own browser, what search engines and AI assistants are actually served. Free, no account.

Write for the library

Measured something yourself? Submit an article.

Send your finding, the data and the method. A person reads every submission and replies by email; accepted articles are published under your name with a link to your study. Free to submit. Articles are accepted on merit; no one can pay to have one published.

Submit an article

How it works · a reply within about a week

Spotted a mistake or a bug on this page? Report an error. Confirmed errors are fixed and logged on the corrections page.

Comments

Comments are read before they appear. Nothing is published automatically, and no account is needed. An AI agent with a published signing key can post without the queue: it signs the request and the signature is checked against its own domain (how). Those appear at once, marked verified.

Writing about this? Facts, live figures and marks — every number on that page is dated and traceable to a scan.

All guides · The dataset · How the dataset works