Advanced Structured Data: Nesting & @graph

Model a whole page as one connected graph of entities using nesting, @id references and @graph.

Beginners add one Article block and move on. At scale, a single page describes several connected things - an organization, a website, a page, an author, a breadcrumb trail - and you want Google to understand how they relate, not just that they exist.

Two ways to connect entities

  • Nesting - put one entity inside another, e.g. an author Person object inside an Article.
  • Referencing with @id - give each entity a stable @id (a URL fragment) and point to it from elsewhere. This avoids repeating the same Organization block on every page.

The @graph pattern

Instead of scattering several <script> blocks, put an array of entities under a single @graph. They share one context, cross-reference by @id, and are far easier to maintain. This is exactly what mature CMS plugins output.

Testing is not optional

One trailing comma disqualifies the whole block. Validate every change with the Rich Results Test (eligibility) and the Schema Markup Validator (syntax), then watch the Search Console Enhancements reports over time to catch regressions at scale.

Example

Example · json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#org",
      "name": "SoundsCode",
      "logo": "https://example.com/logo.png"
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com",
      "publisher": { "@id": "https://example.com/#org" }
    },
    {
      "@type": "Article",
      "@id": "https://example.com/pour-over-guide/#article",
      "headline": "Pour Over Coffee: A Beginner's Guide",
      "isPartOf": { "@id": "https://example.com/#website" },
      "author": { "@id": "https://example.com/#org" }
    }
  ]
}

When to use it

  • An e-commerce site models a product page as an @graph containing Product, BreadcrumbList, and WebPage entities linked by @id references, enabling Google to understand the full page context.
  • A knowledge-base site nests HowTo steps inside an Article @graph node so a single JSON-LD block qualifies the page for both Article Top Stories and HowTo rich results simultaneously.
  • A media company uses sameAs @id links across multiple pages to tell Google that the 'Jane Doe' author entity on every article is the same Person as the one in the Organisation schema.

More examples

@graph with linked entities by @id

An @graph block with @id cross-references between WebPage, BreadcrumbList, and Product lets Google build a connected knowledge graph of the page rather than treating each type in isolation.

Example · json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebPage",
      "@id": "https://example.com/shoes/trail-runner-pro/#webpage",
      "url": "https://example.com/shoes/trail-runner-pro/",
      "name": "Trail Runner Pro — Acme Running",
      "breadcrumb": {"@id": "https://example.com/shoes/trail-runner-pro/#breadcrumb"}
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://example.com/shoes/trail-runner-pro/#breadcrumb",
      "itemListElement": [
        {"@type":"ListItem","position":1,"name":"Home",  "item":"https://example.com/"},
        {"@type":"ListItem","position":2,"name":"Shoes", "item":"https://example.com/shoes/"},
        {"@type":"ListItem","position":3,"name":"Trail Runner Pro"}
      ]
    },
    {
      "@type": "Product",
      "@id": "https://example.com/shoes/trail-runner-pro/#product",
      "name": "Trail Runner Pro",
      "mainEntityOfPage": {"@id": "https://example.com/shoes/trail-runner-pro/#webpage"}
    }
  ]
}

Nested HowTo inside Article @graph

Linking a HowTo entity to an Article via mainEntityOfPage in @graph allows a single page to qualify for both the Top Stories carousel and a step-by-step rich result.

Example · json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Article",
      "@id": "https://example.com/blog/how-to-set-up-2fa/#article",
      "headline": "How to Set Up Two-Factor Authentication",
      "datePublished": "2024-04-01",
      "author": {"@id": "https://example.com/authors/jane-doe/#person"}
    },
    {
      "@type": "HowTo",
      "@id": "https://example.com/blog/how-to-set-up-2fa/#howto",
      "name": "How to Set Up Two-Factor Authentication",
      "step": [
        {"@type":"HowToStep","position":1,"name":"Download an authenticator app"},
        {"@type":"HowToStep","position":2,"name":"Enable 2FA in account settings"},
        {"@type":"HowToStep","position":3,"name":"Scan the QR code"}
      ],
      "mainEntityOfPage": {"@id": "https://example.com/blog/how-to-set-up-2fa/#article"}
    }
  ]
}

Author entity reused across pages

Using a stable @id for the author Person entity on every article page tells Google they all refer to the same individual, consolidating their E-E-A-T authority signals.

Example · json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Person",
      "@id": "https://example.com/authors/jane-doe/#person",
      "name": "Jane Doe",
      "jobTitle": "Senior SEO Strategist",
      "url": "https://example.com/authors/jane-doe/",
      "sameAs": [
        "https://linkedin.com/in/janedoe",
        "https://twitter.com/janedoeseo"
      ]
    },
    {
      "@type": "Article",
      "headline": "Core Web Vitals in 2024",
      "author": {"@id": "https://example.com/authors/jane-doe/#person"}
    }
  ]
}

Related

seo schema introseo testing rich resultsseo breadcrumb product schema

Discussion

  • Be the first to comment on this lesson.