Most sites add structured data as a pile of disconnected blocks — an Organization here, an Article there, a BreadcrumbList somewhere else — and never tell machines that these things relate to each other. The @graph container and proper nesting fix that. They let you connect your schema into a single, linked entity graph, so search engines and AI assistants understand that the article was written by a person who works for your organization, which publishes the site. That connected picture is far more valuable than isolated fragments.
The direct answer: use @graph to hold multiple related entities in one JSON-LD block, and use @id to reference entities across it, so each thing is defined once and linked everywhere it appears. This removes ambiguity and helps machines build the relationships that power rich results and AI citations.
Why disconnected schema underperforms
When you output separate, unrelated schema blocks, a crawler sees a list of facts with no links between them. It might read that a page is an Article and that an Organization exists, but nothing states that this organization published this article or that a named author wrote it and belongs to that organization. Machines resolve entities by connection, so unlinked markup leaves the most valuable information — the relationships — on the table.
Connected markup, by contrast, lets an engine build a small knowledge graph of your site: who published what, who wrote it, what the site is about, and how pages relate. This is the same entity-graph thinking behind our guide to entity SEO and the knowledge graph.
How @graph works
Normally a JSON-LD script describes one thing. @graph lets a single script hold an array of things. You place your Organization, WebSite, WebPage, Article, Person, and BreadcrumbList entities side by side inside one @graph array, then wire them together with references. This is cleaner than scattering five separate scripts across the page and makes the relationships explicit.
The wiring is done with @id. You give each entity a unique, stable @id — usually a URL with a fragment, such as the page URL plus #organization or #author. Then, instead of repeating the full entity wherever it is referenced, you point to it by its @id. The Article's author references the Person's @id; the Article's publisher references the Organization's @id. Each entity is defined once and reused by reference, so the data stays consistent and the graph stays connected. If JSON-LD basics are new to you, start with our practical guide to JSON-LD and Schema.org.
Nesting vs referencing: when to use each
You can express a relationship two ways. Nesting places a full child object inside a parent — for example, an author object written out completely inside the Article. This is simple and fine when the child appears only once and nowhere else needs it.
Reference by @id is better when the same entity appears in multiple places. Your Organization is the publisher of every article, shows up in the WebSite, and may be the subject of LocalBusiness markup. Defining it once with an @id and referencing it everywhere keeps every mention identical and lets the engine merge them into one entity. A good rule: nest for one-off details, reference by @id for anything reused across the page or site. Reusable entities like your organization and locations — see LocalBusiness schema — are prime candidates for a single shared @id.
Common nesting mistakes
- Duplicate, slightly different definitions. Writing your organization three times with three different logos or names creates conflicting entities instead of one. Define it once, reference it.
- Broken or inconsistent @id values. A reference that points to an @id you never defined goes nowhere. Keep @id strings identical everywhere, character for character.
- Over-nesting into an unreadable blob. Deeply nested objects are hard to maintain and easy to break; @graph with references is usually cleaner.
- Never validating. One malformed reference can quietly drop a rich result. Always test.
Connecting your structured data into a single graph is one of the highest-return schema upgrades, because it turns scattered facts into a coherent picture a machine can trust and cite. To check whether your structured data is valid, connected, and actually visible to AI crawlers, run the CheckMy.site scanner.