What is the purpose of @id in JSON-LD?

@id is the entity's globally unique identifier — a URI that distinguishes it from every other entity on the web. Lets search engines know 'this Organization in your schema is the same entity as the one I saw on another page'. Without stable @ids, each page declares a fresh nameless entity that can't be associated with previous mentions.

Does @id have to be a URL that returns content?

No. @id is a URI used as an identifier — it doesn't need to resolve to anything in particular. The convention is to use a URL on your domain with a fragment indicating entity type: https://yoursite.com/#organization. The URL itself doesn't need to return that fragment — it's just a globally unique name.

Should @id include the entity type in the fragment?

Yes by convention. Pattern: https://canonical-url#entity-type. Helps disambiguate when one page has multiple entities. Examples: https://acme.com/#organization, https://acme.com/about#person, https://acme.com/products/widget#product. Within a page's @graph, all entities reference each other via these stable @ids.

Can I reuse @id across pages?

Yes for the same entity. Your Organization @id should be identical on every page that mentions your company. Your homepage Article @id should appear on every article page that references that article. Search engines use this to identify entity continuity across the site.

How to Fix Schema @id Errors

@id is the entity's globally unique identifier in your structured data — a URI that distinguishes "this Organization on this page" from every other entity on the web. Without stable @ids, search engines see disconnected fragments instead of a coherent entity graph. With them, your Organization mentioned on the homepage, About page, and every Article gets recognised as the same entity, accumulating signals. This guide covers the URI conventions, cross-referencing patterns, and the stability rules that make @ids useful.

1. Audit @id usage

Step 1

Find entities missing @id

Run the JSON Checker. Findings include entities declared without @id, entities with non-URI @id (just a string), entities with duplicate @id across blocks pointing at different content.

Step 2

Look for inline embedded entities

Often, Article schema embeds the full Organization object instead of referencing it by @id. Each page that re-embeds is another "fresh" Organization declaration with no link to others on your site.

2. The URI convention

@id should be a URI. Standard pattern: canonical URL + fragment identifier per entity type.

// Site-level entities — use root URL with fragment
"@id": "https://yoursite.com/#organization"
"@id": "https://yoursite.com/#website"

// Page-level entities — use page URL with fragment
"@id": "https://yoursite.com/about#webpage"
"@id": "https://yoursite.com/about#breadcrumb"

// Per-resource entities — use resource URL with fragment
"@id": "https://yoursite.com/blog/post-slug#article"
"@id": "https://yoursite.com/products/widget#product"

// People — use a profile page if you have one
"@id": "https://yoursite.com/team/jane#person"

3. Cross-reference, don't embed

Wrong: embedding Organization in every Article

// Article on /blog/post-1
{
  "@type": "Article",
  "publisher": {
    "@type": "Organization",
    "name": "Acme Co",
    "url": "https://acme.com",
    "logo": "https://acme.com/logo.svg"
  }
}

// Same Article on /blog/post-2 — Organization re-embedded
{
  "@type": "Article",
  "publisher": {
    "@type": "Organization",
    "name": "Acme Co",
    "url": "https://acme.com",
    "logo": "https://acme.com/logo.svg"
  }
}

Each page declares a "new" Organization with no continuity.

Right: reference by @id

// Define Organization once, identified by @id
{
  "@type": "Organization",
  "@id": "https://acme.com/#organization",
  "name": "Acme Co",
  "url": "https://acme.com",
  "logo": "https://acme.com/logo.svg"
}

// Article references via @id
{
  "@type": "Article",
  "publisher": { "@id": "https://acme.com/#organization" }
}

Same @id everywhere = same entity recognised across pages.

4. Full page @graph example

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://acme.com/#organization",
      "name": "Acme Co",
      "url": "https://acme.com",
      "logo": {
        "@type": "ImageObject",
        "@id": "https://acme.com/#logo",
        "url": "https://acme.com/logo.svg",
        "width": 600,
        "height": 60
      }
    },
    {
      "@type": "WebSite",
      "@id": "https://acme.com/#website",
      "url": "https://acme.com",
      "name": "Acme Co",
      "publisher": { "@id": "https://acme.com/#organization" },
      "potentialAction": {
        "@type": "SearchAction",
        "target": "https://acme.com/search?q={search_term_string}",
        "query-input": "required name=search_term_string"
      }
    },
    {
      "@type": "WebPage",
      "@id": "https://acme.com/blog/post-1#webpage",
      "url": "https://acme.com/blog/post-1",
      "isPartOf": { "@id": "https://acme.com/#website" },
      "primaryImageOfPage": { "@id": "https://acme.com/blog/post-1#primaryimage" }
    },
    {
      "@type": "ImageObject",
      "@id": "https://acme.com/blog/post-1#primaryimage",
      "url": "https://acme.com/images/post-1-hero.jpg",
      "width": 1200,
      "height": 630
    },
    {
      "@type": "Article",
      "@id": "https://acme.com/blog/post-1#article",
      "isPartOf": { "@id": "https://acme.com/blog/post-1#webpage" },
      "headline": "Article title",
      "datePublished": "2024-01-15T14:00:00Z",
      "dateModified": "2024-02-03T10:30:00Z",
      "author": { "@id": "https://acme.com/team/jane#person" },
      "publisher": { "@id": "https://acme.com/#organization" },
      "image": { "@id": "https://acme.com/blog/post-1#primaryimage" }
    },
    {
      "@type": "Person",
      "@id": "https://acme.com/team/jane#person",
      "name": "Jane Doe",
      "url": "https://acme.com/team/jane"
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://acme.com/blog/post-1#breadcrumb",
      "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://acme.com/" },
        { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://acme.com/blog/" },
        { "@type": "ListItem", "position": 3, "name": "Article title" }
      ]
    }
  ]
}
</script>

One block, seven typed entities, all cross-referenced. Same @id values appear on every page where these entities are mentioned — search engines reconstruct the full graph.

5. Keep IDs stable

⚠️ Once an @id is in production, don't change it. Stable @ids accumulate authority, review associations, and entity disambiguation over time. Changing breaks all of that.

What stays stable

Organization @id — never changes (use root domain)
Person @id — stable per profile page
Product @id — stable per SKU even if URL changes
Article @id — stable even after URL changes (use a canonical URL pattern)

What can change

WebPage @id — tied to URL, changes with URL
BreadcrumbList @id — page-specific
Specific instance entities — Order, Reservation, etc.

Handle URL changes carefully

If you change a product URL from /products/widget-v1 to /products/widget-v2, the @id should ideally stay the same so search engines associate the new URL with the old entity history. Use a stable SKU-based pattern:

"@id": "https://acme.com/sku/PRD-001#product"

// URL can change, @id stays constant
"url": "https://acme.com/products/widget-v2"

6. Common @id mistakes

Mistake 1: Using non-URI strings

// Wrong — not a URI
"@id": "main-organization"
"@id": "12345"

// Right — proper URI
"@id": "https://acme.com/#organization"

Mistake 2: Different @id same entity

// Page A
"@id": "https://acme.com/#org"

// Page B
"@id": "https://acme.com/organization/1"

// Different IDs = different entities to search engines

Mistake 3: Same @id different entities

// Wrong — every Article has same @id
"@id": "https://acme.com/article"

// Right — unique per article
"@id": "https://acme.com/blog/specific-post#article"

7. Verify

Step 1

Schema.org validator structural check

Pass the page through schema.org validator. It reports unresolved @id references — places where you reference an @id that isn't defined elsewhere in the graph.

Step 2

Knowledge graph check

Search Console → Performance shows queries triggering knowledge panels and entity-based features. Sites with strong @id consistency get more entity-driven impressions over time.

💡 Treat @ids like primary keys in a database — globally unique, stable, never reused. The pattern of URL+fragment per entity type covers 95% of needs. Pick the pattern, document it, and apply it consistently.

📋 Re-run the JSON Checker

Verify @id errors are cleared.

Run JSON Checker →