Structured Data Guide: JSON-LD Architecture with @graph

On most sites, structured data is a collection of standalone schema blocks scattered across the page: an Organization here, an Article there, a BreadcrumbList somewhere else — none of them aware of the others. In this guide, we walk through the architecture that connects every schema into a single @graph, the setup that audits treat as the “gold standard”, with code examples.

Why a @graph architecture?

Google tries to understand the entities on a page (the page, the content, the publisher, the author) and how they relate to each other. Standalone schema blocks leave those relationships ambiguous; they can even end up describing the same organization twice, in two different ways. The @graph + @id reference approach gives you three things:

• One definition, many references: the Organization is defined once; the Article's publisher and the WebPage's publisher both point to the same @id.
• Hierarchy: the content is declared as part of the page, and the page as part of the site — so search engines understand the page type clearly.
• Easier maintenance: brand details are updated in one place, and conflicting copies never appear.

Layers: which schema goes where?

Rule: use the WebSite schema on the home page only. On category pages, use the CollectionPage + ItemList pair, and never leave the name field of ItemList items empty — empty fields trigger validation errors and reduce your chances of earning rich results.

Worked example: an article page

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://www.example.com/#organization",
      "name": "Brand Name",
      "logo": {
        "@type": "ImageObject",
        "url": "https://www.example.com/logo-1200.png",
        "width": 1200, "height": 1200
      },
      "sameAs": [
        "https://www.linkedin.com/company/brand",
        "https://x.com/brand"
      ]
    },
    {
      "@type": "Person",
      "@id": "https://www.example.com/#author-name",
      "name": "Author Name",
      "jobTitle": "SEO Director",
      "url": "https://www.example.com/authors/author-name/"
    },
    {
      "@type": "WebPage",
      "@id": "https://www.example.com/blog/sample/#webpage",
      "url": "https://www.example.com/blog/sample/",
      "name": "Page title",
      "isPartOf": { "@id": "https://www.example.com/#website" },
      "publisher": { "@id": "https://www.example.com/#organization" },
      "breadcrumb": {
        "@type": "BreadcrumbList",
        "itemListElement": [
          { "@type": "ListItem", "position": 1, "name": "Home",
            "item": "https://www.example.com/" },
          { "@type": "ListItem", "position": 2, "name": "Blog",
            "item": "https://www.example.com/blog/" },
          { "@type": "ListItem", "position": 3, "name": "Sample Post" }
        ]
      },
      "mainContentOfPage": { "@id": "https://www.example.com/blog/sample/#article" }
    },
    {
      "@type": "BlogPosting",
      "@id": "https://www.example.com/blog/sample/#article",
      "headline": "Article headline",
      "image": [
        "https://www.example.com/image-16x9.jpg",
        "https://www.example.com/image-1x1.jpg"
      ],
      "datePublished": "2026-08-10T09:00:00+03:00",
      "dateModified": "2026-08-29T09:00:00+03:00",
      "author": { "@id": "https://www.example.com/#author-name" },
      "publisher": { "@id": "https://www.example.com/#organization" }
    }
  ]
}

The details audits catch most often

• Don't publish empty fields. If you can't fill a property (phone, description, name), leave it out entirely; an empty string is a validation error.
• Declarations must reflect reality. If the schema says an image is 1200px, it should really be 1200px; don't declare awards, memberships or reviews that don't exist.
• Provide images in two ratios. Offer the Article image in both 16:9 and 1:1; AI surfaces and Discover prefer different ratios.
• The publisher name is the brand name. Use "name": "Brand", not "name": "www.example.com".
• The breadcrumb should be the full path. Include every level, including the current page; an item isn't required on the last element.
• The author should be a Person. Not a text string, but a real entity backed by a job title, a profile page and sameAs links.
• Keep dates consistent. The date shown on the page, the date in the schema and the sitemap lastmod should all tell the same story.

Testing and monitoring

1. Before publishing: check the syntax with the Schema.org Validator and eligibility with the Rich Results Test.
2. After publishing: track errors and warnings in the rich result reports in Search Console.
3. Run a regression test with every template change — structured data is one of the pieces of infrastructure that breaks most quietly.

If you'd like a ready-made @graph skeleton for your own pages, try our Schema Markup Generator.

Frequently asked questions

Microdata or JSON-LD?

JSON-LD. It's the format Google recommends; it's managed separately from the HTML, carries less risk of errors and supports the @graph architecture.

Does structured data directly affect rankings?

It isn't a direct ranking factor; but through rich result eligibility, entity clarity and being understood correctly on AI surfaces, it has a clear effect on visibility.

Sources

• Google — Introduction to structured data markup in Google Search
• Schema.org — BlogPosting
• Google — SEO Starter Guide