JSON-LD @id and @graph: connect entities across pages
How JSON-LD @id and @graph work: choosing stable identifiers, referencing one Organization or policy site-wide, and checking how your blocks merge.
By Crawlito · 9 min read
In short
- In JSON-LD, @id gives a node an identifier; the W3C specification calls dereferenceable identifiers good practice but not required, so @id is a name, not a link a crawler must fetch.
- Relative @id values such as #organization are resolved against the page's base URL, so the same string on two pages names two different entities; use absolute IRIs for anything shared site-wide.
- The JSON-LD 1.1 specification says that, unless one script is targeted, all application/ld+json scripts on a page are processed and merged into one dataset, so nodes with the same @id are combined.
- Google documents @id references to a return policy, shipping service or member tier defined on a different page, but says a ProductGroup must be repeated on every variant page.
- mainEntity points from a page to the thing it is about, mainEntityOfPage points back from the thing to the page, and schema.org defines each as the other's inverse.
On this page
In JSON-LD, @id gives a node a name, usually an IRI such as https://www.example.com/#organization. Any other node that uses that same IRI as a value, as in "publisher": { "@id": "https://www.example.com/#organization" }, refers to the same entity, so you can define your organization, an author or a return policy once and point at it everywhere. @graph is the container that lets one script hold several such nodes under a single @context. The catch is that the cross-page references Google's documentation describes are limited to a few merchant properties, so a site-wide graph needs a clear rule for what you define in full and what you only reference.
The other posts on this site cover what goes inside those nodes: Organization schema for the properties, sameAs for links to outside profiles, and JSON-LD errors for parse failures and duplicate blocks. This one is about the identifiers that tie the nodes together.
What @id is, and what it is not
The JSON-LD 1.1 specification says that "a node is identified using the @id keyword". It adds that, for nodes to be truly linked, dereferencing the identifier should return a representation of that node. Should, not must. Its section on IRIs is explicit: "While it is a good practice for resource identifiers to be dereferenceable, sometimes this is not practical", and it gives urn:uuid: identifiers as an example.
Three consequences follow:
- An @id is an identifier, not a hyperlink.
https://www.example.com/#organizationdoes not need to return anything special. The fragment#organizationdoes not have to match an HTML element on the page. - It is different from
url.urlis a schema.org property: the web address of the thing, such as your home page.@idis the node's name in the graph. They can share a host and path, and usually should, but they do different jobs. - A node with only
@idis a reference. The specification calls an object that has only the@idkey a node reference: it refers to a node described elsewhere.
schema.org takes the same view. Its data model notes say all its syntaxes have a built-in way to express URIs, naming JSON-LD's @id, and that it is generally preferable to use these rather than the identifier property unless you need to state the kind of identifier.
How to choose stable @id values
The value matters less than keeping it the same, on every page, for as long as the entity exists. A common pattern is a URL you control plus a fragment that names the type:
| Entity | Example @id | Defined in full on |
|---|---|---|
| Organization | https://www.example.com/#organization | Home page or About page |
| WebSite | https://www.example.com/#website | Home page |
| Author | https://www.example.com/authors/maria-lopez#person | The author's profile page |
| Return policy | https://www.example.com/returns#policy | The returns page |
| Shipping service | https://www.example.com/shipping#standard | The shipping page |
| A page itself | https://www.example.com/blog/post-slug#webpage | That page |
Rules that keep it stable:
- Use absolute IRIs for anything shared across pages. The specification says relative IRI references "are resolved relative to the base IRI", and that for a script in HTML the default base IRI is the page's document base URL: its address, unless a
<base>element sets another. So"@id": "#organization"on/aboutbecomeshttps://www.example.com/about#organization, and on/blog/postit becomes a different IRI. Two pages, two organizations. - Use the canonical host and protocol.
http://example.com/#organizationandhttps://www.example.com/#organizationare different identifiers. Pick the form your canonical URLs use. - Do not put anything that changes in it. No query strings, session IDs, language codes you might reorganize, or CMS database IDs that change on migration.
- One entity, one @id. Do not reuse
#organizationfor a subsidiary or a single shop location; give each its own.
Relative fragments are fine for nodes that live on one page only. Google's product variant examples use "@id": "#shipping_policy" and "@id": "#coat_parent" inside a single page's markup, and they resolve to that page's URL plus the fragment.
How @graph holds several nodes in one script
Without @graph, a script holds one top-level node and everything else is nested inside it. With it, you list nodes side by side and connect them with references. The specification says a top-level object with no keys other than @graph and @context expresses the default graph, and that @graph "collects such nodes in an array and allows the use of a shared context".
A blog post page might output this:
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Organization",
"@id": "https://www.example.com/#organization",
"name": "Example Analytics",
"url": "https://www.example.com/"
},
{
"@type": "WebPage",
"@id": "https://www.example.com/blog/schema-ids#webpage",
"url": "https://www.example.com/blog/schema-ids",
"mainEntity": { "@id": "https://www.example.com/blog/schema-ids#article" }
},
{
"@type": "BlogPosting",
"@id": "https://www.example.com/blog/schema-ids#article",
"headline": "How we name our schema nodes",
"mainEntityOfPage": { "@id": "https://www.example.com/blog/schema-ids#webpage" },
"publisher": { "@id": "https://www.example.com/#organization" },
"author": {
"@type": "Person",
"@id": "https://www.example.com/authors/maria-lopez#person",
"name": "Maria Lopez",
"url": "https://www.example.com/authors/maria-lopez"
}
}
]
}Nesting and @graph describe the same data; the difference is how you write it. The specification notes that embedding alone cannot express some shapes, such as loops, and that @id "must be used to connect the nodes" there. A page that points to an article which points back to the page is exactly that kind of loop.
Separate scripts behave much the same way. The specification says that, unless a specific script is targeted, all application/ld+json scripts on a page "MUST be processed and merged into a single dataset". Google's structured data guidelines make a similar point for its own features: when items are in separate blocks on the same page and are more useful linked, for example a recipe and its video, use @id in both so Google knows the video is about the recipe.
Referencing an entity defined on another page
This is where the specification and Google's documentation part ways. In linked data terms, a reference to https://www.example.com/returns#policy on a product page names the same node as the definition on the returns page. Whether a particular consumer goes and looks for that definition is up to the consumer.
The cross-page references we found in Google's documentation are all in its merchant features:
| Property | Where the full node lives | Google's documentation |
|---|---|---|
hasMerchantReturnPolicy on an Offer | A global policy under Organization, on a different page | Merchant listing |
shippingDetails.hasShippingService on an Offer | A global ShippingService under Organization, on a different page | Merchant listing |
validForMemberTier | A MemberProgramTier, nested in MemberProgram under Organization, on a separate page (or defined in Merchant Center) | Merchant listing, marked beta |
For the first two, Google says to reference the global policy "using only the @id keyword". Trimmed to just those two references, an Offer looks like this:
{
"@context": "https://schema.org",
"@type": "Offer",
"hasMerchantReturnPolicy": { "@id": "https://www.example.com/returns#policy" },
"shippingDetails": {
"@type": "OfferShippingDetails",
"hasShippingService": { "@id": "https://www.example.com/shipping#standard" }
}
}For member tiers, Google notes that off-page MemberProgramTier data "might not show up in Google Search right away". If you are fixing a missing shipping or returns warning, the posts on the missing shippingDetails field and return policy exceptions cover the policy properties themselves.
Google also documents the opposite case. Its product variant guide says there is no ProductGroup defined on one page and referenced from another, because the ProductGroup lists attributes shared by the variants, so "the full ProductGroup definition needs to be repeated on each of the variant pages".
For anything outside those documented cases, such as an Article's publisher or author pointing at a node defined only on the home page, Google does not say whether it resolves the reference across pages, and we found no documentation from other search engines or AI systems on how they handle it. The safe pattern is a short local copy:
{
"@context": "https://schema.org",
"@type": "BlogPosting",
"headline": "How we name our schema nodes",
"publisher": {
"@type": "Organization",
"@id": "https://www.example.com/#organization",
"name": "Example Analytics",
"url": "https://www.example.com/"
}
}The full Organization record stays on the home page. Each other page repeats the @id with a few properties that make sense without the rest of the graph, usually name and url. For an author, those are the two sub-properties Google's Article documentation recommends; the Article schema guide covers the rest. Because the @id is identical, a consumer that merges the graph sees one organization; a consumer that reads only this page still gets a name and a URL. Keep the local copy and the full record in agreement, which is easiest when both come from the same template data.
mainEntity versus mainEntityOfPage
These two properties connect a page with the thing it is about, from opposite ends. schema.org defines mainEntity as the primary entity described in a page or other CreativeWork, and mainEntityOfPage as a page for which this thing is the main entity being described. Each is listed as the other's inverse.
| Property | Goes on | Points to | Example |
|---|---|---|---|
mainEntity | The page (WebPage, ProfilePage, FAQPage) | The thing the page is about | WebPage, then the BlogPosting |
mainEntityOfPage | The thing | The page that describes it | BlogPosting, then its WebPage or URL |
You need only one direction; the example above uses both to show the pairing. schema.org's notes add two distinctions worth keeping. mainEntity is a narrower form of about: about can list several topics, while mainEntity is the single primary one. And on a page showing a news article about a person, the page's mainEntity is the article, while about would more properly point to the person. mainEntityOfPage can also be used on pages that are not authoritative for the entity, such as a retailer's page for a product, where sameAs would point to the manufacturer's page.
How to check the merged result
A validator tells you whether your markup parses and which items it detects. It is harder to see the merged picture: which identifiers are defined, which are only referenced, and whether two blocks give the same @id different values. This script fetches a page, walks every JSON-LD block, resolves relative @id values against the page URL and reports all three:
import sys, re, json
from urllib.parse import urljoin
from urllib.request import urlopen, Request
url = sys.argv[1]
html = urlopen(Request(url, headers={"User-Agent": "Mozilla/5.0"})).read().decode("utf-8", "replace")
blocks = re.findall(r"<script[^>]*application/ld\+json[^>]*>(.*?)</script>", html, re.S | re.I)
nodes, refs = {}, set()
def walk(obj):
if isinstance(obj, list):
for item in obj:
walk(item)
elif isinstance(obj, dict):
if "@id" in obj:
iri = urljoin(url, obj["@id"])
props = {k: v for k, v in obj.items() if k not in ("@id", "@context")}
if not props:
refs.add(iri)
node = nodes.setdefault(iri, {}) if props else {}
for k, v in props.items():
if k in node and node[k] != v and isinstance(v, (str, int, float)):
print("CONFLICT ", iri, k, repr(node[k]), "vs", repr(v))
node.setdefault(k, v)
for k, v in obj.items():
if k != "@context":
walk(v)
for i, block in enumerate(blocks, 1):
try:
walk(json.loads(block))
except json.JSONDecodeError as e:
print("BLOCK", i, "does not parse:", e)
for iri, props in nodes.items():
print("DEFINED ", iri, props.get("@type"))
for iri in sorted(refs - nodes.keys()):
print("REF ONLY ", iri)Save it as check_ids.py and run python3 check_ids.py https://www.example.com/blog/schema-ids. Typical output on a page with problems:
CONFLICT https://www.example.com/#organization name 'Example Analytics' vs 'Example Analytics Ltd'
DEFINED https://www.example.com/#organization Organization
DEFINED https://www.example.com/blog/schema-ids#article BlogPosting
REF ONLY https://www.example.com/returns#policyRead it like this:
- CONFLICT means two blocks, often a theme and a plugin, describe one entity differently. Merging keeps both values, so fix the source rather than hoping one wins.
- REF ONLY is fine for the documented cross-page cases, such as a return policy. For anything else, add a local copy with the key properties.
- An organization IRI that contains the page path, such as
/blog/schema-ids#organization, means a relative@idslipped in. Make it absolute. - Run it on several templates. The home page, an article, a product and the returns page should all print the same organization IRI.
The script resolves IRIs against the page URL and ignores a <base> element; if your pages set one, relative values resolve against its href instead. For a full expansion, paste a block into the JSON-LD Playground, which the specification links from its examples.
Frequently asked questions
Does the URL in @id have to load?
No. The JSON-LD specification calls dereferenceable identifiers good practice but says this is sometimes not practical. Using a real page URL plus a fragment is still sensible, because it is a stable address you already control.
Should @id be the same as url?
Not exactly. url is the web address of the thing, while @id names the node, and a fragment such as #organization keeps the organization distinct from the home page node, which shares the same address.
Is @graph better than nesting?
Neither is better for consumers; they express the same data. @graph is easier when several nodes reference each other or when a CMS outputs nodes from separate components.
Can I put Organization markup only on the home page and reference it everywhere else?
Google says Organization markup does not need to be on every page, but it does not document resolving a general @id reference from another page. Keep the full record on the home page and repeat the @id with a name and URL where another node, such as an article's publisher, needs it.
Does connecting entities with @id help AI search?
No AI search operator documents how it reads @id or merges JSON-LD graphs. A connected, consistent graph removes contradictions for any system that does read it; it does not guarantee citations or rich results.
Check the markup a crawler actually receives
Run the script above on your main templates after any theme or plugin change, because that is when duplicate nodes and relative identifiers usually appear. To see what a crawler gets from a single page, including its JSON-LD in the raw HTML, run the free check. For the same review across a whole site with evidence and prioritized fixes, an audit covers up to 500 pages.
Filed under Structure and schema. Topics: json-ld, structured-data, google