Give each entity one stable @id, put all entities in a single @graph array, and reference other entities with {"@id": "..."} instead of repeating or nesting them. In JSON-LD, @id is the node identifier that lets other nodes in the graph refer to a node unambiguously [1]. Google says the same thing in practice: when separate items on a page are more useful linked together, use @id in both items so Google can understand their relationship [2].

This article covers the id convention, a complete example for Organization, WebSite, WebPage and Article, the mistakes that break the graph, and how to check it.

What @id and @graph do

Two JSON-LD features carry the whole approach:

  • **@id** names a node. Any other node can point to it by repeating that value.
  • **@graph** holds several node objects in one document. JSON-LD 1.1 allows an object containing @graph to represent a graph object [1].

Without them, you get isolated blocks: an Organization in one script tag, an Article in another, and nothing that says the Article's publisher is that Organization. A publisher property containing only a name string is also a disconnected fact. A publisher pointing to {"@id": "https://example.com/#organization"} is a link to a specific node.

Google recommends JSON-LD because it is the easiest format for site owners to implement and maintain at scale [5]. A shared template that emits one graph per page fits that.

An id convention that holds up

An @id is an identifier, not a page you have to serve. It does not need to return anything when requested. It does need to be consistent. A common convention is the page URL plus a fragment naming the entity:

Entity@idDefined on
Organizationhttps://example.com/#organizationEvery page (same id, same data)
WebSitehttps://example.com/#websiteEvery page
WebPagehttps://example.com/blog/my-post/#webpageThat page only
Articlehttps://example.com/blog/my-post/#articleThat page only

Rules to follow:

  • Use absolute URLs. A relative id can resolve differently depending on where the document is read.
  • Pick one host and scheme. https://www.example.com/ and https://example.com/ produce two different ids. So do a trailing slash on one and not the other.
  • Name the fragment after the type. #organization, #website, #webpage, #article. Anyone reading the markup can tell what each id refers to.
  • Base page-level ids on the canonical URL. See the canonical tags guide for how to settle which URL that is.
  • **Prefer https://schema.org in @context.** Schema.org says both http://schema.org and https://schema.org are understood, but https is the preferred form in its examples [7].

A complete example

One <script> block, one @graph, four nodes. All values are placeholders.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Example Co",
      "url": "https://example.com/",
      "logo": "https://example.com/assets/logo.png"
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com/",
      "name": "Example Co",
      "publisher": { "@id": "https://example.com/#organization" }
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/blog/my-post/#webpage",
      "url": "https://example.com/blog/my-post/",
      "name": "My Post",
      "isPartOf": { "@id": "https://example.com/#website" },
      "primaryImageOfPage": "https://example.com/assets/my-post.png"
    },
    {
      "@type": "Article",
      "@id": "https://example.com/blog/my-post/#article",
      "headline": "My Post",
      "datePublished": "2025-01-15",
      "dateModified": "2025-02-01",
      "mainEntityOfPage": { "@id": "https://example.com/blog/my-post/#webpage" },
      "isPartOf": { "@id": "https://example.com/blog/my-post/#webpage" },
      "author": { "@id": "https://example.com/#organization" },
      "publisher": { "@id": "https://example.com/#organization" }
    }
  ]
}
</script>

The links, in plain terms:

  • WebSite publisher points to Organization.
  • WebPage isPartOf points to WebSite.
  • Article mainEntityOfPage and isPartOf point to WebPage.
  • Article author and publisher point to Organization. If the piece has a named human author, define a Person node with its own @id and point author there instead.

Use the most specific Article subtype that is true for the content (BlogPosting or NewsArticle, for example), and include only properties you can back up with visible page content.

Reference, don't repeat

Compare the two patterns for the publisher:

// Before: a copy that can drift
"publisher": {
  "@type": "Organization",
  "name": "Example Co",
  "logo": "https://example.com/old-logo.png"
}

// After: a pointer to the single definition
"publisher": { "@id": "https://example.com/#organization" }

The "before" version means every place that embeds the organization can carry a different logo, a different name, or a typo. The "after" version has one definition per document.

Where each node lives

Define the full Organization and WebSite nodes in the graph on every page, using the same id and the same data each time. Google's documentation describes linking items that are on the same page [2]. As far as public documentation goes, it does not promise that a bare reference on one page will pull in a definition from another URL. Putting the full node in each page's graph avoids relying on that.

The WebPage and Article nodes are specific to the page they describe, so each page gets its own pair of ids.

Pitfalls

Changing ids. If one deploy emits #organization and a later one emits #org or /#/schema/Organization/1, every reference you wrote elsewhere (templates, plugins, other blocks) now points at nothing. Pick a convention once, document it in the template, and treat the ids as part of your site's public interface. Changing the host, scheme or trailing-slash policy changes every id derived from it.

Dangling references. {"@id": "https://example.com/#publisher"} with no node that defines #publisher is a link to nothing. This usually happens when two plugins use different naming.

Duplicate blocks. A CMS theme, an SEO plugin and a hand-written snippet can each emit their own Organization. You end up with three nodes for one company, possibly with different ids and conflicting data. Pick one source of truth and turn the others off.

The same id defined twice with different data. If two blocks both claim #organization with different names or logos, a consumer has to guess which wins. Merge them into one node.

Duplicate pages with different markup. Google's guidelines say to use the same structured data on all page duplicates, not just on the canonical page [4]. If you generate ids from the canonical URL, duplicates then carry the same ids as well as the same data. That is our reading of how the two guidelines fit together, not a documented requirement.

Assuming valid means displayed. Google says structured data does not guarantee rich-result display, even when it is marked up correctly and passes the Rich Results Test [4]. A clean graph is a precondition, not a result.

How to validate

Check in layers:

  1. Syntax and graph shape. The Schema Markup Validator can fetch a page or validate pasted markup, extract JSON-LD, RDFa and Microdata, and display a summary of the extracted graph [3]. Look at the tree: the Article should show its publisher, and the WebPage its parent WebSite, as populated nodes rather than empty ones.
  2. Google's view. Google points to the Rich Results Test and the Schema Markup Validator for checking an implementation [6].
  3. Your own reference check. Neither tool will tell you your convention drifted. A short script can: it fetches a URL, collects every node that has an @id, and reports duplicates and dangling references.
import json, re, sys, urllib.request

url = sys.argv[1]
html = urllib.request.urlopen(url).read().decode("utf-8", "replace")
blocks = re.findall(
    r'<script[^>]+application/ld\+json[^>]*>(.*?)</script>', html, re.S)

defined, refs = {}, set()

def walk(x):
    if isinstance(x, dict):
        i = x.get("@id")
        if i:
            if len(x) == 1:
                refs.add(i)          # bare reference
            else:
                defined[i] = defined.get(i, 0) + 1
        for v in x.values():
            walk(v)
    elif isinstance(x, list):
        for v in x:
            walk(v)

for b in blocks:
    walk(json.loads(b))

print("blocks:", len(blocks))
print("duplicate definitions:", [i for i, n in defined.items() if n > 1])
print("dangling references:", sorted(refs - set(defined)))

Run it against the URLs a crawler would request. If it reports problems, fix them in the template or plugin configuration that generates the markup, then run it again. Treat the template as the source of truth and the fetched output as the check on it. Run it on a sample of page types: a post, a category page, the home page.

What to do next

  1. Write down your id convention (host, scheme, trailing slash, fragment names) in the template.
  2. Find every source of JSON-LD on your site: theme, plugins, hand-written snippets. Keep one.
  3. Emit one @graph per page with Organization, WebSite, WebPage and Article, linked by @id.
  4. Validate in the Schema Markup Validator, then run the reference check on a sample of live URLs.

For type-by-type property guidance, see Schema.org markup for AI search. For the wider list of checks around it, use the technical SEO checklist.