To connect several JSON-LD blocks, put their entities in one @graph array under a single @context, give each entity a stable @id such as https://example.com/#organization, and replace every repeated nested copy of an entity with a reference that holds only that @id. Then confirm that the page shows the same facts, and test the JSON.
When a theme, a plugin, an app or hand-written code each print their own block, the same organization, author or page ends up described in more than one place with nothing tying the descriptions together. Merging them gives you one set of entities that point at each other.
@graph organizes the data and makes the relationships explicit. It does not create a ranking boost, and it does not produce a rich result on its own. Six fictional nodes on example.com show the pattern: Organization, WebSite, WebPage, Article, Person and BreadcrumbList.
Learn the four JSON-LD keywords first
JSON-LD is JSON that describes linked data, and four keys that start with an at sign do the connecting work. Each one is defined in the W3C JSON-LD 1.1 specification. Keys and values are case-sensitive, so @id and @ID are different things, and Article is not article.
@contexttells a parser how short words such asname,authorandArticlemap to full web addresses."https://schema.org"supplies the Schema.org vocabulary.@graphholds a group of related nodes. At the top of a document it lets several entities share one@context.@idgives a node a unique identifier written as a web address. Any other node can reuse that address to point at it.@typesays what the node is, for exampleOrganization,WebPage,ArticleorPerson.
A node is one described thing, and an entity is the real thing the node describes. A reference is an object that holds only an @id, so it points at a node defined somewhere else in the graph. Every merged graph depends on that difference between a definition and a reference.
Choose a stable @id for every entity
An @id is a name, and a good name does not change. Build it from a canonical URL plus a short fragment: https://example.com/#organization for the company, https://example.com/#website for the site, and https://example.com/blog/graph/#webpage for one page. The address does not have to load anything. It only has to be unique and permanent.
Site-level entities keep the same @id on every page. The organization is https://example.com/#organization on the home page, on every article and on the contact page, which is how a parser can tell that all those mentions are one organization. Page-level entities take the page URL as their base, so the Article and the BreadcrumbList of one page are different nodes from those of the next page.
Use the same canonical URL for the page node that the page declares as its canonical link. If the page is reachable with and without a trailing slash, pick one form and use it in the @id, the url and the breadcrumb. Avoid anything that changes, such as a date, a session value or a database row number that a later migration could renumber.
The guide to organization schema on every page covers keeping the shared organization consistent across a whole site. The guide to entity SEO with sameAs covers pointing a node at the profiles that identify the same entity elsewhere.
See how the six nodes connect
The example describes one article page and links its entities through @id. The relationships run in a fixed pattern, and each arrow below is a property whose value is a reference to another node.
WebSite.publisherpoints to theOrganization.WebPage.isPartOfpoints to theWebSite.WebPage.mainEntitypoints to theArticle, andWebPage.breadcrumbpoints to theBreadcrumbList.Article.authorpoints to thePerson, andArticle.publisherpoints to theOrganization.Article.mainEntityOfPagepoints to theWebPage, andArticle.isPartOfpoints to theWebSite.- Each
ListItem.itemin the breadcrumb holds a page URL.
Schema.org defines author as accepting a Person or an Organization, isPartOf as linking a work to a larger work such as a website, and mainEntityOfPage as naming the page for which a thing is the main subject. Your own site may use fewer links. A site with no individual authors can point Article.author at the Organization instead.
For a local business, the organization node can use a more specific type. The guide to local business schema shows which fields belong there, and the same @id approach applies.
Copy the six-node example and replace the values
The example below is teaching code. Every name, URL, image address, date and profile in it is fictional and uses the reserved example.com domain, so replace each one with a fact that appears on your real page. It is split into two valid JSON documents to keep each readable: the site-level nodes first, then the page-level nodes. On a real page you put all six nodes in one @graph array.
The first block defines the Organization, the WebSite and the Person. The WebSite points at the organization with a reference, and the Person points at it through worksFor.
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Organization",
"@id": "https://example.com/#organization",
"name": "Northstar Example Media",
"url": "https://example.com/",
"logo": "https://example.com/images/logo.png",
"sameAs": ["https://social.example.com/northstar-example"]
},
{
"@type": "WebSite",
"@id": "https://example.com/#website",
"url": "https://example.com/",
"name": "Northstar Example Media",
"alternateName": "Northstar Media",
"publisher": { "@id": "https://example.com/#organization" }
},
{
"@type": "Person",
"@id": "https://example.com/authors/river-lee/#person",
"name": "River Lee",
"url": "https://example.com/authors/river-lee/",
"worksFor": { "@id": "https://example.com/#organization" }
}
]
}Change the name and url of the organization and website first. Keep alternateName only if your site has a real short name. Replace logo with the address of a logo file on your site, and list in sameAs only profiles that belong to the organization. The Person needs the author's real name and, when an author page exists, that page's URL.
The second block holds the page-level nodes. Each reference in it points at an @id from the first block or from another node in this one.
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "WebPage",
"@id": "https://example.com/blog/graph/#webpage",
"url": "https://example.com/blog/graph/",
"name": "Using @graph to Connect Your Schema Into One Entity Map",
"isPartOf": { "@id": "https://example.com/#website" },
"breadcrumb": { "@id": "https://example.com/blog/graph/#breadcrumb" },
"mainEntity": { "@id": "https://example.com/blog/graph/#article" }
},
{
"@type": "Article",
"@id": "https://example.com/blog/graph/#article",
"url": "https://example.com/blog/graph/",
"headline": "Using @graph to Connect Your Schema Into One Entity Map",
"image": "https://example.com/images/graph-16x9.png",
"datePublished": "2026-08-01T09:00:00-06:00",
"dateModified": "2026-08-20T14:30:00-06:00",
"author": { "@id": "https://example.com/authors/river-lee/#person" },
"publisher": { "@id": "https://example.com/#organization" },
"mainEntityOfPage": { "@id": "https://example.com/blog/graph/#webpage" },
"isPartOf": { "@id": "https://example.com/#website" }
},
{
"@type": "BreadcrumbList",
"@id": "https://example.com/blog/graph/#breadcrumb",
"itemListElement": [
{ "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
{ "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://example.com/blog/" },
{ "@type": "ListItem", "position": 3, "name": "Using @graph to Connect Your Schema Into One Entity Map", "item": "https://example.com/blog/graph/" }
]
}
]
}Here the headline, image, datePublished and dateModified must match what the real article page shows. The breadcrumb names and URLs must follow the trail a visitor sees on the page. When you join the two documents, keep one @context, put the six objects in one @graph array and keep every @id exactly as written.
Merge the blocks your site already prints
Start with what is already on the page, because a theme, an SEO plugin or an app may print several blocks without telling you. View the page source, or use the rendered-page view of a testing tool, and list every <script type="application/ld+json"> element along with the entities each one describes. The guide to organization schema explains why a second description of the same organization is a problem.

For each entity, pick one block to be the definition and write down its @id. Then change every other block that mentions the entity so that it holds only a reference to that @id. If a plugin already outputs a graph, the cleaner fix is usually to adjust its settings, or to add your missing nodes to the graph it outputs, rather than adding a second block that restates the organization.
Where two blocks disagree, for example two different logo files or two spellings of the company name, decide which value is true and visible on the page, and keep only that one. A merged graph that repeats a contradiction is no better than two separate blocks that contradict each other.
Replace repeated nested entities with @id references
The most common cause of duplicates is nesting. A plugin writes the full organization inside WebSite.publisher, writes it again inside Article.publisher, and a third block adds it a third time. The nodes look identical to a reader but a parser sees three descriptions that may drift apart.

The block below is valid JSON, and it shows the pattern to remove. The publisher object is a full definition in two places, with a different logo address in each.
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "WebSite",
"@id": "https://example.com/#website",
"url": "https://example.com/",
"publisher": {
"@type": "Organization",
"name": "Northstar Example Media",
"logo": "https://example.com/images/logo.png"
}
},
{
"@type": "Article",
"@id": "https://example.com/blog/graph/#article",
"headline": "Using @graph to Connect Your Schema Into One Entity Map",
"publisher": {
"@type": "Organization",
"name": "Northstar Example Media",
"logo": "https://example.com/images/logo-old.png"
}
}
]
}Define the organization once as a node with its own @id, as in the first block of the six-node example. Then replace each nested copy with "publisher": { "@id": "https://example.com/#organization" }. The reference carries no name or logo of its own, which is the point: the facts live in one place, so they cannot disagree.
A definition and a reference are both objects, so they can look alike. The difference is the contents. A definition has a @type and properties that describe the thing. A reference has only an @id, and it means "the node with this identifier, defined elsewhere in the graph".
Know which properties each engine asks for
A graph can be valid JSON and valid Schema.org vocabulary and still miss what one search feature needs. These are four separate levels: JSON syntax, Schema.org vocabulary, the requirements of a specific Google feature, and whether the result is indexed and shown. Passing one does not imply the next, and "required" should always name the engine and the feature behind it.
Google says that its Article structured data has no required properties, and recommends properties such as headline, image, datePublished, dateModified and author. Google's Organization structured data documentation also lists no required properties, and recommends name, url, logo and sameAs where they apply.
Google's site names documentation asks for name and url on the WebSite, and treats alternateName as optional for sites with a short name. Google's breadcrumb documentation sets the breadcrumb requirements: itemListElement, and for each ListItem a position, a name and an item, except that the last item may rely on the containing page URL.
The WebPage node is a valid Schema.org type, and Google documents no separate rich-result feature for a generic WebPage. It is still worth having in the graph, because it is the hub that the website, article and breadcrumb connect to. The publisher properties are valid Schema.org relationships that are optional for the Google features above.
Google announced in October 2024 that it was retiring the sitelinks search box, and the same post says site names continue to work from WebSite markup. A WebSite node is therefore still used for site names, and it keeps the graph connected.
Make the graph readable for Bing and AI search
The nodes in the graph are the same for every engine. Bing supports Schema.org in JSON-LD, Microdata and RDFa, so one graph serves it, and Copilot web search uses Bing-indexed content. Yandex does not support every Schema.org type, according to its markup questions page.
To be included in ChatGPT Search, allow OAI-SearchBot (ChatGPT Search help page); for Perplexity, allow PerplexityBot (crawler documentation). Keep the page crawlable, show the important facts in visible HTML, and see whether AI systems use schema markup.
Add the graph to your page
Put the finished document in a script element of type application/ld+json in the HTML of the page. Most sites place it in the head of the page. The element carries only the JSON, with no extra text around it.
<script type="application/ld+json">
<!-- paste the complete JSON-LD document here -->
</script>Which route you use depends on the platform. A theme setting, an SEO plugin, a tag manager, a custom-code field or a template file can each add the element, and the current official instructions for your platform say where it goes. Check what the platform already prints first, so that you extend that output instead of adding a second description of the same entities.
If a script adds the markup after the page loads, Google's JavaScript structured data guidance says to test the rendered page with the Rich Results Test or URL Inspection. Rendered markup is a different thing from the HTML a simple fetch returns, so make sure the test you use reads the version crawlers will see.
The graph describes the page that carries it. The site-level nodes repeat on every page with the same @id, and the page-level nodes change from page to page. Keep every fact in the graph visible to readers on that page, because Google's general structured data guidelines ask for markup that reflects visible content.
You can build the graph in the browser with the Schema Nova @graph builder, which joins nodes under one @context and shows the references.
Test the graph in the right tool
Choose the test that matches the question you are asking. The Schema Markup Validator checks Schema.org vocabulary and JSON-LD syntax. Google's Rich Results Test checks the features Google supports, and Search Console URL Inspection shows how Google read the rendered page.
For Bing, use the Markup Validator or the Markup card in Bing URL Inspection. For Yandex, use its structured data validator, and for Apple, use the validation tool in Apple's markup guide. Each engine reports on its own rules, so a clean result in one is not a clean result in another.
The JSON-LD Playground is a useful viewer for the graph itself. It expands the context and shows each node with its identifier, so you can see whether a reference resolves to a defined node.
For a quick syntax pass on code you paste, the Schema Nova schema validator reports JSON problems, and the Schema Nova schema checker looks at markup on a page. A passing test means the markup was read as intended. It does not promise a search appearance, a ranking or a citation.
Fix common problems in a merged graph
Most graph problems come from five causes, and each has a direct fix.
A reference with no matching definition is the first. If author points to https://example.com/authors/river-lee/#person and no node has that @id, the link goes nowhere. Search the graph for the exact string and make sure one node defines it, character for character.
The second is @id values that differ slightly. A trailing slash, http instead of https, or a different capital letter creates a second identifier. Copy each @id from one place instead of typing it again.
The third is invalid JSON: a trailing comma, a missing quotation mark, or a comment, which JSON does not allow. Run the code through a JSON-aware tool before you publish. The fourth is a mismatch with the page, such as an author named in the graph who appears nowhere on the page. Fix it by adding the visible fact or removing the node.
The fifth is two graphs left in place after a merge, one from a plugin and one from your own code. Find each script element in the source and remove or reconfigure the one you no longer need. Then run the tests again from the top.
Questions people ask
What is @graph in JSON-LD?
@graph is a key that holds a group of related nodes in one JSON-LD document. It lets several entities, such as an organization, a page and an article, share one @context while each keeps its own @id. It organizes the data and is not a ranking signal.
Do I need @graph if I have only one schema entity?
No. A single entity works as one plain JSON-LD object. @graph becomes useful when you describe two or more entities that relate to each other, or when you want to merge blocks into one document.
Can I use several JSON-LD blocks instead of one @graph?
Yes. Google says it can understand multiple structured data elements on one page. Separate blocks can still connect through the same @id values, but one @graph is easier to read, maintain and test.
Does @graph guarantee a rich result?
No. Google says structured data can make a page eligible for richer appearances but does not guarantee that one will show, and Bing says its annotations do not guarantee a visually rich snippet. A graph organizes relationships, and each provider decides how to use eligible markup.
Should the same Organization node appear on every page?
Yes, when the page belongs to that organization. Use the same @id and the same facts each time so every page points at one organization. The page-level nodes change with each page.
